[Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs
Jean-Paul Calderone
exarkun at divmod.com
Mon Jul 24 09:59:52 EDT 2006
On Sun, 23 Jul 2006 19:11:04 -0600, Glyph Lefkowitz <glyph at wolfwood.twistedmatrix.com> wrote:
>Author: glyph
>Date: Sun Jul 23 19:11:03 2006
>New Revision: 17664
>
>Modified:
> branches/addamp-1715/twisted/protocols/amp.py
>Log:
>This was pre-UQDS code, so in making the transition I have to add lots of docs
>
> [snip]
>
> class Argument:
>+ """ Base-class of all objects that take values from Amp packets and convert
>+ them into objects for Python functions.
>+ """
Blech. Does this style of docstring formatting make anyone else barf?
I notice that jml pointed out on the review of #1940 that the coding
standard nominally requires this. Two points:
* I think the coding standard is unclear in what it is trying to
communicate. It gives an example of a docstring with no leading newline
and from this one might infer that all docstrings should omit leading
newlines, when really it is suggesting that simple, single-line lead-ins
to docstrings belong on the same line as the opening triple quotes.
* I don't think what the coding standard says is actually relevant
anymore. This was a display hack to appease a very old version of epydoc.
pydoctor and even the current version of epydoc don't care about this
whitespace.
I think the style prevalent throughout the unit tests is ideal:
"""
Blah.
"""
This is the easiest to read. It is unfortunate the emacs has such a hard
time with this construct, but I think it is what we should adopt anyway.
Jean-Paul
More information about the Twisted-Python
mailing list