Re: [Twisted-Python] doc bloat

2014-12-04 Thread Glyph
> On Dec 3, 2014, at 18:46, exar...@twistedmatrix.com wrote: > > On 12:55 am, gl...@twistedmatrix.com wrote: >> >>> On Dec 2, 2014, at 20:05, exar...@twistedmatrix.com wrote: >> >>> Are there lots of useless docstrings on nested function definitions purely >>> for the sake of twistedchecker?

Re: [Twisted-Python] doc bloat

2014-12-03 Thread Adi Roiban
On 3 December 2014 at 00:55, Glyph wrote: > > > On Dec 2, 2014, at 20:05, exar...@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 bi

Re: [Twisted-Python] doc bloat

2014-12-03 Thread exarkun
On 12:55 am, gl...@twistedmatrix.com wrote: On Dec 2, 2014, at 20:05, exar...@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 diffic

Re: [Twisted-Python] doc bloat

2014-12-02 Thread Glyph
> On Dec 2, 2014, at 20:05, exar...@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? twisted

Re: [Twisted-Python] doc bloat

2014-12-02 Thread exarkun
On 10:02 am, a...@roiban.ro wrote: As a Twisted API users, I don't find a big problem the fact that __repr__ docstring is presented by pydoctor together with the other method, As a Twisted contributor, I don't like when I have to copy/paste docstring from an interface or from an inherited cla

Re: [Twisted-Python] doc bloat

2014-12-02 Thread Adi Roiban
As a Twisted API users, I don't find a big problem the fact that __repr__ docstring is presented by pydoctor together with the other method, As a Twisted contributor, I don't like when I have to copy/paste docstring from an interface or from an inherited class ... or too explicity state that the t

Re: [Twisted-Python] doc bloat

2014-11-30 Thread Glyph
> On Nov 30, 2014, at 16:09, Glyph wrote: > 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 >

Re: [Twisted-Python] doc bloat

2014-11-30 Thread HawkOwl
On 30 Nov 2014, at 23:09, Glyph 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 > deve