On 30 Nov 2014, at 23:09, Glyph <gl...@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
signature.asc
Description: Message signed with OpenPGP using GPGMail
_______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
