[Twisted-Python] doc bloat

[Adi Roiban]

On 3 December 2014 at 00:55, Glyph <glyph at twistedmatrix.com> wrote:

>
> > On Dec 2, 2014, at 20:05, exarkun at twistedmatrix.com wrote:
>
> > Are there lots of useless docstrings on nested function definitions
> purely for the sake of twistedchecker?  Or are there undocumented nested
> functions that are actually a little bit difficult to understand on their
> own?
>
>
> twistedchecker does not presently require nested function

>From my experience, even nested functions need a sentence to describe
them....there are many nested functions used as deferred callbacks and I
prefer to have a sentence describing when they are called.

For callback methods I still don't know whether I should name based on what
they do or after the condition in which they are called. I prefer to name
them after what they do, but also to document in the docstring the
condition

But I don't think that nested functions required extensive apidoc/pydoctor
markup.

----------

In order to survey the current code, maybe we can create a wiki page, and
while reading/writing/reviewing code we can extract examples and put them
in the wiki page.

-- 
Adi Roiban
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20141203/f94d6e90/attachment-0002.html>