[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.
"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.
- 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:
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