Merge pull request #11390 from cabalism/doc/todo-autogenerated-modules

Remove todo for autogenerated modules

Author: mergify[bot]

doc/cabal-package-description-file.rst

@@ -3019,25 +3019,36 @@ Autogenerated modules and includes
 
 .. pkg-section:: None
 
-Modules that are built automatically at setup, created with a custom
-setup script, must appear on :pkg-field:`other-modules` for the library,
-executable, test-suite or benchmark stanzas or also on
-:pkg-field:`library:exposed-modules` for libraries to be used, but are not
-really on the package when distributed. This makes commands like sdist fail
-because the file is not found.
-
-These special modules must appear again on the :pkg-field:`autogen-modules`
-field of the stanza that is using them, besides :pkg-field:`other-modules` or
-:pkg-field:`library:exposed-modules`. With this there is no need to create
-complex build hooks for this poweruser case.
+Autogenerated modules are not included with the package source. Instead, they
+are built automatically at setup or created with a custom setup script and must
+appear twice for a component: once to flag them as being autogenerated in an
+:pkg-field:`autogen-modules` field, and again to bring them into the component
+with a listing in :pkg-field:`other-modules` or
+:pkg-field:`library:exposed-modules`.
+
+.. note::
+
+    Files :file:`Paths_{pkgname}` and :file:`PackageInfo_{pkgname}`,
+    autogenerated modules with package :ref:`version <package-version-info>` and
+    :ref:`package-related <package-related-info>` information, are typically
+    exposed so that they're accessible with the library.
+
+    Creating a source distribution with ``cabal sdist`` reports any source files
+    not found and fails. Listing modules as :pkg-field:`autogen-modules` exempts
+    ``cabal sdist`` from finding files for these modules.
+
+.. error::
+
+    An autogenerated module cannot also be the :pkg-field:`executable:main-is`
+    file. The ``cabal sdist`` command expects to find this file in the source
+    tree and autogenerated modules are generated outside the source tree.
 
 .. pkg-field:: autogen-modules: module list
    :since: 2.0
 
-   .. todo:: document autogen-modules field
-
-Right now :pkg-field:`executable:main-is` modules are not supported on
-:pkg-field:`autogen-modules`.
+   A list of autogenerated modules. Each one of these modules must also be
+   listed elsewhere as if they were modules on disk.  Autogenerated modules are
+   not packaged by the ``cabal sdist`` command.
 
 ::
 
@@ -3065,9 +3076,9 @@ Right now :pkg-field:`executable:main-is` modules are not supported on
 .. pkg-field:: autogen-includes: filename list
    :since: 3.0
 
-   A list of header files from this package which are autogenerated
-   (e.g. by a ``configure`` script). Autogenerated header files are not
-   packaged by ``sdist`` command.
+   A list of header files from this package which are autogenerated (e.g. by a
+   ``configure`` script).  Autogenerated header files are not packaged by
+   the ``cabal sdist`` command.
 
 
 .. _accessing-data-files:
@@ -3131,6 +3142,8 @@ hyphens converted into underscores, and ``var`` is either ``bindir``,
 the configured data directory for ``pretty-show`` is controlled with the
 ``pretty_show_datadir`` environment variable.
 
+.. _package-version-info:
+
 Accessing the package version
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -3142,6 +3155,8 @@ The auto generated :file:`PackageInfo_{pkgname}` module exports the constant
 which is defined as the version of your package as specified in the
 ``version`` field.
 
+.. _package-related-info:
+
 Accessing package-related information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^