<html><head><meta http-equiv="Content-Type" content="text/html charset=us-ascii"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; ">A long time ago, we made an informal policy decision about redundancy between documentation of instance variables and constructor parameters. &nbsp;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. &nbsp;Arbitrarily, we decided that @ivar is the one we would standardize on.<div><br></div><div>Later, we decided that too many attributes were public and we should default to making more things private.</div><div><br></div><div>The unfortunate confluence of these decisions has resulted in API documentation like this:<br><div><br></div><div>&lt;<a href="http://twistedmatrix.com/documents/12.2.0/api/twisted.web.client.Agent.html">http://twistedmatrix.com/documents/12.2.0/api/twisted.web.client.Agent.html</a>&gt;</div></div><div><br></div><div>Note that the public "__init__" is undocumented, but all the private, greyed-out attributes have documentation.</div><div><br></div><div>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 <i>different</i>&nbsp;names than the parameters to __init__, since they all start with _.</div><div><br></div><div>Of course, it would still be super redundant to document everything twice if the parameters and the attributes are in fact the same.</div><div><br></div><div>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. &nbsp;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.</div><div><br></div><div>(And perhaps it should be officially documented in the coding standard.)</div><div><br></div><div>Thoughts, anyone? &nbsp;Shall I file a ticket?</div><div><br></div><div>-glyph</div></body></html>