[Twisted-Python] doc suggestion

exarkun at twistedmatrix.com exarkun at twistedmatrix.com
Thu Nov 15 04:48:25 MST 2012


On 08:03 am, glyph at twistedmatrix.com wrote:
>A long time ago, we made an informal policy decision about redundancy 
>between documentation of instance variables and constructor parameters. 
>Specifically we decided that if an initializer simply takes a bunch of 
>parameters, then sets them as attributes on self under the same name, 
>it would be redundant to document them both with @ivar and with @param. 
>Arbitrarily, we decided that @ivar is the one we would standardize on.
>
>Later, we decided that too many attributes were public and we should 
>default to making more things private.
>
>The unfortunate confluence of these decisions has resulted in API 
>documentation like this:
>
><http://twistedmatrix.com/documents/12.2.0/api/twisted.web.client.Agent.html>
>
>Note that the public "__init__" is undocumented, but all the private, 
>greyed-out attributes have documentation.
>
>This is technically a violation of the original policy statement - 
>although nobody can really be blamed for that, since as far as I can 
>tell it's not actually written down anywhere - in that the @ivars have 
>different names than the parameters to __init__, since they all start 
>with _.
>
>Of course, it would still be super redundant to document everything 
>twice if the parameters and the attributes are in fact the same.
>
>However, I think that going forward, this tendency should be amended so 
>that, in the case where the attributes are private but the __init__ 
>parameters are public, they should be documented with @param statements 
>and not with @ivar statements.  More generally, if the same thing has 
>to be documented twice, and it's public in one place and private in the 
>other, the public documentation should always be preferred.
>
>(And perhaps it should be officially documented in the coding 
>standard.)

I agree.  Actually, I think a few people have even started doing this 
already.  I suppose we should document it, although I bet I can count on 
one hand how many people have actually _read_ the coding standard in the 
last year.
>Thoughts, anyone?  Shall I file a ticket?

A ticket for updating the coding standard?  Yes.  I don't think there 
should be a ticket for correcting the existing documentation - perhaps a 
milestone, instead (clearly there's too much documentation to change to 
do it for a single ticket)?

Jean-Paul




More information about the Twisted-Python mailing list