[Twisted-Python] doc suggestion

[Glyph]

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.)

Thoughts, anyone?  Shall I file a ticket?

-glyph
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://twistedmatrix.com/pipermail/twisted-python/attachments/20121115/323b2e26/attachment.htm