Docs: fix misleading description of Build_doctests; release 1.0.12

README.md

@@ -86,9 +86,11 @@ To recap the example's code:
    main = defaultMainWithDoctests "doctests"
    ```
 
-   Assuming your test-suite is called `doctests`, this `Setup` will generate a `Build_doctests`
-   module during package build. If your test-suite goes by name `foo`,
-   `defaultMainWithDoctests "foo"` creates a `Build_foo` module.
+   This `Setup` will generate a `Build_doctests` module during package build.
+
+   Note that the module name `Build_doctests` is a fixed constant, and it is
+   not related to the `"doctests"` argument. That argument identifies which
+   `test-suite` (among those defined in your .cabal file) will run the doctest.
 
 4. Use the generated module in a testsuite, simply like so:
 
@@ -152,7 +154,7 @@ main = for_ components $ \(Component name flags pkgs sources) -> do
 ```
 
 There is also a more explicit approach: if you have an executable named `foo`, then
-`Build_doctest` will contain `flags_exe_foo`, `pkgs_exe_foo`, and `module_sources_exe_foo`.
+`Build_doctests` will contain `flags_exe_foo`, `pkgs_exe_foo`, and `module_sources_exe_foo`.
 If the name has hyphens in it (e.g., `my-exe`), `cabal-doctest` will convert them to
 underscores (e.g., you'd get `flags_my_exe`, `pkgs_my_exe`, `module_sources_my_exe`).
 Internal library `bar` values will have a `_lib_bar` suffix.

changelog.md

@@ -1,5 +1,7 @@
 # 1.0.12 -- 2025-11-19
 
+* Fix documentation mistake regarding `Build_doctests` module name. [cabal-doctest#90][]
+* Clarify function signatures through a meaningful alias onto `String`.
 * Refresh CI & `tested-with` GHC versions.
 
 [cabal-doctest#90]: https://github.com/ulidtko/cabal-doctest/issues/90

src/Distribution/Extra/Doctest.hs

@@ -8,8 +8,7 @@
 
 -- | See cabal-doctest README for full-fledged recipes & caveats.
 --
--- The provided 'generateBuildModule' generates a @Build_{suffix}@ module, with
--- caller-chosen @suffix@ that is usually @"doctests"@ -- module @Build_doctests@.
+-- The provided 'generateBuildModule' generates a module named @Build_doctests@.
 --
 -- That module exports just enough compiler flags, so that doctest could be simply
 --
@@ -42,6 +41,7 @@
 -- from @setup-depends@: 'defaultMainWithDoctests' and 'defaultMainAutoconfWithDoctests'.
 --
 module Distribution.Extra.Doctest (
+    TestSuiteName,
     defaultMainWithDoctests,
     defaultMainAutoconfWithDoctests,
     addDoctestsUserHook,
@@ -221,6 +221,10 @@ mkVersion ds = Version ds []
 -- Mains
 -------------------------------------------------------------------------------
 
+-- | This type is a 'String' which identifies a test-suite in your cabal-file;
+-- the one you'll be running doctest from.
+type TestSuiteName = String
+
 -- | A default @Setup.hs@ main with doctests:
 --
 -- @
@@ -230,23 +234,30 @@ mkVersion ds = Version ds []
 -- main :: IO ()
 -- main = defaultMainWithDoctests "doctests"
 -- @
+--
+-- The argument @"doctests"@ identifies a test-suite in your cabal-file; the
+-- one you'll run doctest from. If you have @test-suite my-test@, you should
+-- invoke @defaultMainWithDoctests "my-test"@ in Setup.hs.
+--
+-- This argument does not change the generated module name imported from the
+-- test-driver's @Main@ -- that one always remains @import Build_doctests@.
 defaultMainWithDoctests
-    :: String  -- ^ doctests test-suite name
+    :: TestSuiteName
     -> IO ()
 defaultMainWithDoctests = defaultMainWithHooks . doctestsUserHooks
 
 -- | Like 'defaultMainWithDoctests', but for packages with @build-type: Configure@.
 --
 -- @since 1.0.2
 defaultMainAutoconfWithDoctests
-    :: String  -- ^ doctests test-suite name
+    :: TestSuiteName
     -> IO ()
 defaultMainAutoconfWithDoctests n =
     defaultMainWithHooks (addDoctestsUserHook n autoconfUserHooks)
 
 -- | 'simpleUserHooks' with 'generateBuildModule' already wired-in.
 doctestsUserHooks
-    :: String  -- ^ doctests test-suite name
+    :: TestSuiteName
     -> UserHooks
 doctestsUserHooks testsuiteName =
     addDoctestsUserHook testsuiteName simpleUserHooks
@@ -256,7 +267,7 @@ doctestsUserHooks testsuiteName =
 -- This is exported for advanced custom Setup-s.
 --
 -- @since 1.0.2
-addDoctestsUserHook :: String -> UserHooks -> UserHooks
+addDoctestsUserHook :: TestSuiteName -> UserHooks -> UserHooks
 addDoctestsUserHook testsuiteName uh = uh
     { buildHook = \pkg lbi hooks flags -> do
         generateBuildModule testsuiteName flags pkg lbi
@@ -319,7 +330,7 @@ data Component = Component Name [String] [String] [String]
 --     }
 -- @
 generateBuildModule
-    :: String -- ^ doctests test-suite name
+    :: TestSuiteName
     -> BuildFlags -> PackageDescription -> LocalBuildInfo -> IO ()
 generateBuildModule testSuiteName flags pkg lbi = do
   let verbosity = fromFlag (buildVerbosity flags)
@@ -598,7 +609,7 @@ testDeps :: ComponentLocalBuildInfo -> ComponentLocalBuildInfo
 testDeps xs ys = nub $ componentPackageDeps xs ++ componentPackageDeps ys
 
 amendGPD
-    :: String -- ^ doctests test-suite name
+    :: TestSuiteName
     -> GenericPackageDescription
     -> GenericPackageDescription
 #if !(MIN_VERSION_Cabal(2,0,0))