[Twisted-Python] doc bloat

[exarkun at twistedmatrix.com]

On 10:02 am, adi at 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 class ...

I hate it when people do this, too.  I never want anyone to do this. 
When I review changes in which this appears, I ask the author to change 
the submission to include useful, non-redundant documentation instead.

The coding standard doesn't explicitly say that you should not copy the 
docstring from an implementation to an interface - but this is a good 
example of the kind of thing our documentation can't be expected to 
cover.  Copying an interface docstring to an implementation is just one 
of the many possible bad practices a developer could engage in; a list 
of all possible bad practices would make the developer documentation 
infinitely long.

To the larger issue, I think the most productive thing to do would be to 
actually look at our code base and see if there are glaring examples of 
useless documentation.  If we can generalize from these examples to a 
rule, we can add that rule to the project policy (preferably encoded in 
a tool, not as prose in the developer documentation).

I'm a little bit tempted to agree with the `__repr__` case.  People who 
are reading the API documentation might not be put off by documentation 
for these methods but are they helped in any way?  I think that most of 
the time they probably aren't.  I'm basing this on times I can recall 
having written a `__repr__` docstring and how I had to struggle to put 
useful words into that docstring instead of pointless boilerplate.  I 
still think it would be good to collect a bunch of actual `__repr__` 
docstrings from Twisted and see if such evidence supports this 
conclusion.
>or too explicity state
>that the type of None is NoneType... and then to add a link to it :)

It sounds like there's agreement on this point, at least.  For what it's 
worth, this seems uncontroversial to me: the type of `None` is 
`NoneType` and the only instance of `NoneType` is `None`.  Documenting 
one or the other conveys all possible information there is to convey so 
documenting one should be enough.  Even if we wanted the rendered 
version of the documentation for this case to be redundant, pydoctor can 
synthesize that redundancy - it doesn't need the source material to be 
redundant.
>
>>As a first approximation, I think we could ask twistedchecker to stop
>enforcing docstring requirements for objects directly matching a 
>"private"
>naming pattern.
>
>Is there a ticket/issue for that?
>What does `stop enforcing docstring requirements` mean?
>
>I think that docstring are important, and testing code or private 
>methods
>is still code which should be maintained and it should have docstrings, 
>but
>it would be nice not to ask for
>strict @param @type @return @rtype.

Eh.  Test code has to be maintained just like anything else.  As the de 
facto specification for most features, it's perhaps (but only perhaps) 
more important to have everything clearly documented in a test suite.  I 
think that requiring parameter and return type documentation in the test 
suite is a very good thing.

However, requiring the same degree of documentation for *all* code may 
not be necessary.  If a test method defines a simple nested function, 
perhaps that doesn't need a docstring.  This is another thing we could 
inspect the current Twisted codebase for.  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?

Jean-Paul
>-------
>
>+1 for getting serious about twistedcker ...
>
>I would be happy to help with twistedchecker, as well as with the other
>automated tools.
>
>What do you say if we put all problems/issues/comments here
>https://github.com/twisted/twistedchecker/issues
>and have 2 or 3 people who can decide if an issues is accepted, or help
>define the right behaviour or reject it and then also review the pull
>requests.
>
>Right now there are many "undecided" or not tagged tickets, and I don't
>know which one is a real problem or not.
>
>One important requirement to move things forward is to provide quick
>feedback, both for the initial issue report and the review.
>Waiting months to get feedback from a patch is not fun and is a sign 
>that
>core developers don't care about the newly proposed changes.
>
>----------
>
>+1 for getting serious about the other code checkers: pyflakes and
>pydoctor. Right now, is a PITA to run all these tools on your local
>computer ...
>
>Cheers
>--
>Adi Roiban