[Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs
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:
>Date: Sun Jul 23 19:11:03 2006
>New Revision: 17664
>This was pre-UQDS code, so in making the transition I have to add lots of docs
> 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
I think the style prevalent throughout the unit tests is ideal:
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.
More information about the Twisted-Python