[Doc-SIG] How should variables' docstrings be written?

[Edward Loper]

Epydoc 3 supports extracting information about Python modules by
parsing.  As a result, it can extract "docstrings" for variables.
There are several possible ways these docstrings could be expressed in
the Python source file, and I wanted to get some feedback on which
ways people prefer.  It's my hope that some consensus can be reached
on this, so that any tools that extract variable docstrings can use
the same conventions.

The conventions I've seen are:

     class A:

         a = 1
         """string literal following the assignment"""

         ##
         # Comment whose first line starts with a double-hash,
         # preceeding the assignment.
         b = 2

         #: Comment that begins with a special marker string on all
         #: lines, preceeding the assignment
         c = 3

         d = 4  #: Comment w/ marker on the same line the as assignment

         e = [
             #: Comment w/ special marker, within the value expression.
             1,
             2,
             3]

String literal:
   This is the closest form to existing docstrings.  I think it works
   well if the assignment line is fairly short, but for multiline
   values (eg large dictionaries or multiline strings), the docstring
   can become too far from the name of the variable it describes.
   Also, if the value is a multiline string, the division between
   the end of the value and the start of the docstring isn't obvious.

Comment whose first line is a double hash:
   This is used by doxygen and Fredrik Lundh's PythonDoc.  In doxygen,
   if there's text on the line with the double hash, it is treated as
   a summary string.  I dislike this convention because it seems too
   likely to result in false positives.  E.g., if you comment-out a
   region with a comment in it, you get a double-hash.

Comment that begins with a special marker string:
   This is my current favorite.  But there's a question of what the
   special marker string should be.  Enthought proposes "#*", partially
   because it works well with line wrapping for some versions of emacs.
   But if a different marker string is deciced on, then python-mode.el
   could certainly be made aware of it.  The markers that look
   reasonably good to my eye are:

     #: #| #*

Currently, epydoc supports both string literals and comments with the
special marker "#:".  The comment-docstrings can be placed before the
assignment, after it on the same line, or within the value (or any
combination thereof).

So..  Which conventions do people prefer?

-Edward