[Twisted-Python] doc suggestion
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
I want to unsubscribe please;
At 2012-11-15 16:03:39,Glyph glyph@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.)
Thoughts, anyone? Shall I file a ticket?
-glyph
On 08:03 am, glyph@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)?
Jean-Paul
On Nov 15, 2012, at 3:48 AM, exarkun@twistedmatrix.com wrote:
On 08:03 am, glyph@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:
-g
participants (3)
-
exarkun＠twistedmatrix.com -
Glyph -
王富文