[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