[Twisted-Python] doc suggestion

[Glyph]

On Nov 15, 2012, at 3:48 AM, exarkun at twistedmatrix.com wrote:

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

Done:

<http://tm.tl/6189>

-g