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