diff --git a/doc/cabal-package-description-file.rst b/doc/cabal-package-description-file.rst
index a5e87c065af..1df235fb2df 100644
--- a/doc/cabal-package-description-file.rst
+++ b/doc/cabal-package-description-file.rst
@@ -3019,25 +3019,31 @@ 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::
+
+    Listing modules in :pkg-field:`autogen-modules` exempts ``cabal sdist`` from
+    finding their source files. Creating a source distribution with ``cabal
+    sdist`` reports any source files not found and fails.
+
+.. 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 +3071,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: