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

glyph at divmod.com glyph at divmod.com
Tue Jul 25 11:16:42 EDT 2006

On Tue, 25 Jul 2006 10:07:44 +1000, Jonathan Lange <jml at mumak.net> wrote:
>I don't have strong feelings about how docstrings should be formatted.
>However I would prefer it if we used PEP 257 formatting.

I just read PEP 257.  What features in particular are you referring to?  Most of it seems to be about encoding redundant information.

By section:

"What is a Docstring?"
 - I think we all know
 - "Use triple quotes", sure.

"One Line Docstrings"  Hopefully we should have only a few of these, it seems odd to dedicate so much verbiage to them.

"Multi-Line Docstrings"
 - One-line summary: not always possible.  Following another aspect of our coding standard, a "line", in a method-level docstring, is at most 72 characters, you've burned a minimum of 8 in indentation, and that's often not enough space to summarize.  One sentence summary?  Sure.
 - Blank line before and after class docstrings?  I don't see this followed anywhere.  Especially not *before* docstrings: the convention is:
    class X:
        """ ...
pretty much everywhere.  I don't see any reason to change it.
 - "docstring of a script..." not applicable because of t.p.u.O
 - "list the classes..." not applicable because of pydoctor
 - "docstring for a function..." ... yes, it should describe arguments, side effects, return values; what else would it do?
 - "docstring for a class..." not applicable again because of pydoctor; this information is redundant
 - "if a class subclasses another class..." not applicable again because of pydoctor's inheritance listing
 - "DO NOT use the Emacs convention..." uh yeah, also don't spell all your method names wrong or use synonyms for them

"handling docstring indentation" 
 - this whole section is about docstring processing tools, which, unless I manage to convince mwh to embed pydoctor in lore for some reason, Twisted is not :).

More information about the Twisted-Python mailing list