How should variables' docstrings be written?

classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

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

_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: How should variables' docstrings be written?

John M. Gabriele
--- Edward Loper <[hidden email]> wrote:

> [snip]
>
> Comment that begins with a special marker string:
>    This is my current favorite.  [snip]
>    The markers that look
>    reasonably good to my eye are:
>
>      #: #| #*
>
> [snip]
>
> So..  Which conventions do people prefer?
>
> -Edward
>

I like that one too because it saves space and also b/c
it comes before the variable. I never understood why
docstrings come *after* the thing they're describing...

Anyway, I think any of your suggestions look pretty good
to the eye, and with proper syntax highlighting they will
all stand out nicely in one's editor.

I'd prefer #@ or #% though, since they're easier to type.
I can hold down the shift key with my right pinky and
just hit those two keys (3-2 or 3-5) very quickly without
missing a beat.

---John


__________________________________________________
Do You Yahoo!?
Tired of spam?  Yahoo! Mail has the best spam protection around
http://mail.yahoo.com 
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: How should variables' docstrings be written?

Michael Foord-5
In reply to this post by Edward Loper
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  -  [hidden email]
> http://mail.python.org/mailman/listinfo/doc-sig
>
>  


_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: How should variables' docstrings be written?

David Goodger
In reply to this post by Edward Loper
[Edward Loper]
> So..  Which conventions do people prefer?

I prefer string literals after the assignments.  If you support doc
comments, I suggest allowing the marker to be specified per-module.

--
David Goodger <http://python.net/~goodger>


_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig

signature.asc (257 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: How should variables' docstrings be written?

Edward Loper
David Goodger wrote:
> [Edward Loper]
>> So..  Which conventions do people prefer?
>
> I prefer string literals after the assignments.  If you support doc
> comments, I suggest allowing the marker to be specified per-module.
>

How would it be specified?  Some __special_variable__?

-Edward
_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig
Reply | Threaded
Open this post in threaded view
|

Re: How should variables' docstrings be written?

David Goodger
> David Goodger wrote:
>> I prefer string literals after the assignments.  If you support doc
>> comments, I suggest allowing the marker to be specified per-module.

[Edward Loper]
> How would it be specified?  Some __special_variable__?

Sure, __docmarker__ perhaps.

--
David Goodger <http://python.net/~goodger>


_______________________________________________
Doc-SIG maillist  -  [hidden email]
http://mail.python.org/mailman/listinfo/doc-sig

signature.asc (257 bytes) Download Attachment