[Doc-SIG] How should variables' docstrings be written?
Michael Foord
fuzzyman at voidspace.org.uk
Fri Mar 17 22:49:49 CET 2006
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
>
>
More information about the Doc-SIG
mailing list