[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]

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