On 3 December 2014 at 00:55, Glyph <glyph@twistedmatrix.com> wrote:
On Dec 2, 2014, at 20:05, exarkun@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