#431: Doc comments for attributes can now be given on the same line as the assignment.

CHANGES

@@ -81,6 +81,9 @@ Release 1.1 (in development)
 
 * #306: Added :event:`env-get-outdated` event.
 
+* #431: Doc comments for attributes can now be given on the same line as
+  the assignment.
+
 * #590: Added ``caption`` option to graphviz directives.
 
 * #537: Added :confval:`nitpick_ignore`.

doc/ext/autodoc.rst

@@ -198,16 +198,23 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
    used for automatic member documentation.
 
    For module data members and class attributes, documentation can either be put
-   into a special-formatted comment *before* the attribute definition, or in a
-   docstring *after* the definition.  This means that in the following class
-   definition, all attributes can be autodocumented::
+   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
+   immediately after the assignment *on the same line*.  The latter form is
+   restricted to one line only.
+
+   This means that in the following class definition, all attributes can be
+   autodocumented::
 
       class Foo:
           """Docstring for class Foo."""
 
           #: Doc comment for class attribute Foo.bar.
+          #: It can have multiple lines.
           bar = 1
 
+          flox = 1.5   #: Doc comment for Foo.flox. One line only.
+
           baz = 2
           """Docstring for class attribute Foo.baz."""
 
@@ -220,6 +227,8 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
    .. versionchanged:: 0.6
       :rst:dir:`autodata` and :rst:dir:`autoattribute` can now extract docstrings.
+   .. versionchanged:: 1.1
+      Comment docs are now allowed on the same line after an assignment.
 
    .. note::
 

sphinx/pycode/__init__.py

@@ -85,10 +85,30 @@ class AttrDocVisitor(nodes.NodeVisitor):
             self.in_init -= 1
 
     def visit_expr_stmt(self, node):
-        """Visit an assignment which may have a special comment before it."""
+        """Visit an assignment which may have a special comment before (or
+        after) it.
+        """
         if _eq not in node.children:
             # not an assignment (we don't care for augmented assignments)
             return
+        # look *after* the node; there may be a comment prefixing the NEWLINE
+        # of the simple_stmt
+        parent = node.parent
+        idx = parent.children.index(node) + 1
+        while idx < len(parent):
+            if parent[idx].type == sym.SEMI:
+                idx += 1
+                continue  # skip over semicolon
+            if parent[idx].type == sym.NEWLINE:
+                prefix = parent[idx].get_prefix()
+                if not isinstance(prefix, unicode):
+                    prefix = prefix.decode(self.encoding)
+                docstring = prepare_commentdoc(prefix)
+                if docstring:
+                    self.add_docstring(node, docstring)
+                    return  # don't allow docstrings both before and after
+            break
+        # now look *before* the node
         pnode = node[0]
         prefix = pnode.get_prefix()
         # if the assignment is the first statement on a new indentation

tests/test_autodoc.py

@@ -425,6 +425,7 @@ def test_generate():
                    ('attribute', 'test_autodoc.Class.udocattr'),
                    ('attribute', 'test_autodoc.Class.mdocattr'),
                    ('attribute', 'test_autodoc.Class.inst_attr_comment'),
+                   ('attribute', 'test_autodoc.Class.inst_attr_inline'),
                    ('attribute', 'test_autodoc.Class.inst_attr_string'),
                    ('method', 'test_autodoc.Class.moore'),
                    ])
@@ -621,6 +622,7 @@ class Class(Base):
         docstring="moore(a, e, f) -> happiness")
 
     def __init__(self, arg):
+        self.inst_attr_inline = None #: an inline documented instance attr
         #: a documented instance attribute
         self.inst_attr_comment = None
         self.inst_attr_string = None