Jean-Paul raised a salient point about documentation on a ticket
<https://twistedmatrix.com/trac/ticket/4804#comment:21> recently. To quote
that:
We seem to be going the direction of "document every possible thing" these
days. This stems from good intentions but the result is ever more bloated
developer documentation of which any individual contributor has an ever
shrinking knowledge. Rather than continuing to block the docs even further ...
I think we need to get serious about pursuing a different strategy - for
example, making twistedchecker a piece of software we could actually maintain
and the output of which we could actually rely on (this really is just an
example - the notion of a tool that tells you every single thing that's wrong
with a piece of software is, of course, quite enticing - but perhaps
unachievable).
I think we've been moving in the direction of making twistedchecker
maintainable, although it does still present some challenges. For example,
I've been wanting to eliminate this
<https://github.com/twisted/twistedchecker/issues/75
<https://github.com/twisted/twistedchecker/issues/75>> for a while, but I just
haven't been able to figure it out.
I am also thinking that we may want to create a category of private
implementation details that don't require docstring coverage. In a public API,
every parameter, every attribute, every detail should have accompanying prose
and type annotations. In the innards of an implementation, these details can
crowd out the code they're supposed to be elucidating.
As a first approximation, I think we could ask twistedchecker to stop enforcing
docstring requirements for objects directly matching a "private" naming pattern.
Thoughts?
-glyph
_______________________________________________
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
