[Twisted-Python] Re: [Twisted-commits] r17664 - This was pre-UQDS code, so in making the transition I have to add lots of docs

[Jonathan Lange]

On 7/24/06, Jean-Paul Calderone <exarkun at divmod.com> wrote:
> 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.

The standard is definitely unclear.

I don't have strong feelings about how docstrings should be formatted.
 However I would prefer it if we used PEP 257 formatting.

Also, I strongly object to using
"""
Blah.
"""
for one line docstrings.


-0 on changing docstring format
+1 on updating coding standard to be clearer

jml