<html><head><meta http-equiv="Content-Type" content="text/html charset=us-ascii"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class="">Jean-Paul raised a salient point about documentation <a href="https://twistedmatrix.com/trac/ticket/4804#comment:21" class="">on a ticket</a> recently. To quote that:<div class=""><div id="changelog" style="border-top-left-radius: 0.35em; border-top-right-radius: 0.35em; border-bottom-right-radius: 0.35em; border-bottom-left-radius: 0.35em; padding: 0.35em 0px 0px; border: none; margin-bottom: 1.5em; -webkit-box-shadow: none; box-shadow: none;" class=""><div class="change" id="trac-change-21-1417022487471732" style="padding: 2em 1em; border-width: 1px; border-style: solid; border-color: rgb(221, 221, 221) rgb(170, 170, 170) rgb(170, 170, 170) rgb(221, 221, 221); border-top-left-radius: 0.35em; border-top-right-radius: 0.35em; border-bottom-right-radius: 0.35em; border-bottom-left-radius: 0.35em; margin-top: 1em; position: relative; background-color: rgb(231, 231, 231); background-position: initial initial; background-repeat: initial initial;"><div class="comment searchable" style="margin-left: 2em;"><p class="">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).</p><div class=""></div></div></div></div></div><div class=""><div style="border-top-left-radius: 0.35em; border-top-right-radius: 0.35em; border-bottom-right-radius: 0.35em; border-bottom-left-radius: 0.35em; padding: 0.35em 0px 0px; border: none; margin-bottom: 1.5em; -webkit-box-shadow: none; box-shadow: none;" class="">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 <<a href="https://github.com/twisted/twistedchecker/issues/75" class="">https://github.com/twisted/twistedchecker/issues/75</a>> for a while, but I just haven't been able to figure it out.</div></div><div style="border-top-left-radius: 0.35em; border-top-right-radius: 0.35em; border-bottom-right-radius: 0.35em; border-bottom-left-radius: 0.35em; padding: 0.35em 0px 0px; border: none; margin-bottom: 1.5em; -webkit-box-shadow: none; box-shadow: none;" class="">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.</div><div style="border-top-left-radius: 0.35em; border-top-right-radius: 0.35em; border-bottom-right-radius: 0.35em; border-bottom-left-radius: 0.35em; padding: 0.35em 0px 0px; border: none; margin-bottom: 1.5em; -webkit-box-shadow: none; box-shadow: none;" class="">As a first approximation, I think we could ask twistedchecker to stop enforcing docstring requirements for objects directly matching a "private" naming pattern.</div><div style="border-top-left-radius: 0.35em; border-top-right-radius: 0.35em; border-bottom-right-radius: 0.35em; border-bottom-left-radius: 0.35em; padding: 0.35em 0px 0px; border: none; margin-bottom: 1.5em; -webkit-box-shadow: none; box-shadow: none;" class="">Thoughts?</div><div style="border-top-left-radius: 0.35em; border-top-right-radius: 0.35em; border-bottom-right-radius: 0.35em; border-bottom-left-radius: 0.35em; padding: 0.35em 0px 0px; border: none; margin-bottom: 1.5em; -webkit-box-shadow: none; box-shadow: none;" class="">-glyph</div></body></html>