[Twisted-Python] doc bloat

[Glyph]

> On Dec 3, 2014, at 18:46, exarkun at twistedmatrix.com wrote:
> 
> On 12:55 am, 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 definitions to have docstrings.  I recently merged a fix to an incongruity where it was requiring this of classes defined within functions: <https://github.com/twisted/twistedchecker/commit/4af4e97f99d6e5f683b65272a8dbe7bce2087aa7>. So this one, at least, we can cross off for the future :).
> 
> The broader context of this suggestion was that we should inspect the codebase to see what policy changes would improve the quality of the code/documentation while reducing the effort required to develop and maintain it.
> 
> It sounds like you have some ideas about such changes already.  Does that mean you'd like to suggest them (presumably in the form of issues filed against twistedhecker) instead of doing this investigation?

In this one case, I believed I was simply bringing our tooling into line with existing policy.  twistedchecker already doesn't require docstrings on callbacks, it seemed like a clear bug that it required docstrings on those callbacks if they existed inside a class statement.

The letter of the policy is a little ambiguous, and perhaps it should be updated.  <https://twistedmatrix.com/documents/current/core/development/policy/coding-standard.html#docstrings <https://twistedmatrix.com/documents/current/core/development/policy/coding-standard.html#docstrings>> says docstrings "should" always be used, but it doesn't say "must".  And, as written, it has no exception for callbacks, which clearly contravenes our existing tooling and practice.

I do have a couple of other more specific ideas and I will almost certainly file twistedchecker issues for them :).

More broadly speaking I think it would be great to have some investigation into our code-quality issues.  I think that there are definitely lots of useless docstrings for the sake of twistedchecker, and I'm not quite sure how to classify those.

-glyph
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20141204/20995ae4/attachment-0002.html>