[Twisted-Python] doc suggestion
Glyph
glyph at twistedmatrix.com
Thu Nov 15 18:09:30 MST 2012
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
More information about the Twisted-Python
mailing list