<div style="line-height:1.7;color:#000000;font-size:14px;font-family:arial"><br>I want to <span class="keyword">unsubscribe please;</span><br><br><br><div></div><div id="divNeteaseMailCard"></div><br>At 2012-11-15 16:03:39,Glyph&nbsp;&lt;glyph@twistedmatrix.com&gt; wrote:<br> <blockquote id="isReplyContent" style="PADDING-LEFT: 1ex; MARGIN: 0px 0px 0px 0.8ex; BORDER-LEFT: #ccc 1px solid">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></blockquote></div><br><br><span title="neteasefooter"><span id="netease_mail_footer"></span></span>