diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index ab520f70c..859ca6fc2 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -194,12 +194,13 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
                    automethod
                    autoattribute
 
-   These work exactly like :rst:dir:`autoclass` etc., but do not offer the options
-   used for automatic member documentation.
+   These work exactly like :rst:dir:`autoclass` etc., but do not offer the
+   options used for automatic member documentation.
 
    For module data members and class attributes, documentation can either be put
-   into a special-formatted comment, or in a docstring *after* the definition.
-   Comments need to be either on a line of their own *before* the definition, or
+   into a comment with special formatting (using a ``#:`` to start the comment
+   instead of just ``#``), or in a docstring *after* the definition.  Comments
+   need to be either on a line of their own *before* the definition, or
    immediately after the assignment *on the same line*.  The latter form is
    restricted to one line only.