470,604 Members | 2,297 Online
Bytes | Developer Community
New Post

Home Posts Topics Members FAQ

Post your question to a community of 470,604 developers. It's quick & easy.

How should variables' docstrings be written?

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
Mar 17 '06 #1
0 1007

This discussion thread is closed

Replies have been disabled for this discussion.

Similar topics

2 posts views Thread by Sridhar R | last post: by
reply views Thread by Craig Ringer | last post: by
2 posts views Thread by Steven Bethard | last post: by
reply views Thread by Michael Muller | last post: by
6 posts views Thread by Kamilche | last post: by
12 posts views Thread by jelle | last post: by
4 posts views Thread by Lawrence D'Oliveiro | last post: by
6 posts views Thread by Steve Brown | last post: by
By using this site, you agree to our Privacy Policy and Terms of Use.