[Twisted-Python] doc bloat

[HawkOwl]

On 30 Nov 2014, at 23:09, Glyph <glyph at twistedmatrix.com> wrote:

> Jean-Paul raised a salient point about documentation on a ticket 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> 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

This sounds like a good idea. How do we tackle things that should be documented in some form (ie. important implementation details), that do need docstring-like things, but should not be exposed to users? For example, http://twistedmatrix.com/documents/current/api/twisted.web.http.Request.html#__repr__ , to an application developer, has no use, and is just cluttering up the docs, but may want to have a docstring for code documentation purposes, rather than user documentation purposes.

It’s like, 11pm here, so apologies if that made zero sense :)

-hawkie
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 455 bytes
Desc: Message signed with OpenPGP using GPGMail
URL: </pipermail/twisted-python/attachments/20141130/ccff589a/attachment.sig>