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

[Michael Foord]

Edward Loper wrote:
> Epydoc 3 supports extracting information about Python modules by
> parsing.  As a result, it can extract "docstrings" for variables.
>   
Fantastic news.

> 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
>
>   
My preference. :-)

>          #: Comment that begins with a special marker string on all
>          #: lines, preceeding the assignment
>   
As the colon is a character with special significance within Python
syntax, I would find this distracting when reading code.

>          c = 3
>
>          d = 4  #: Comment w/ marker on the same line the as assignment
>
>   
Inline comments are generally uglier.

>          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:
>
>      #: #| #*
>
>   
Bearable. :-)

Fuzzyman
http://www.voidspace.org.uk/python/index.shtml

> 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
>
> _______________________________________________
> Doc-SIG maillist  -  Doc-SIG at python.org
> http://mail.python.org/mailman/listinfo/doc-sig
>
>