I want to unsubscribe please;
At 2012-11-15 16:03:39,Glyph <gl...@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
_______________________________________________
Twisted-Python mailing list
Twisted-Python@twistedmatrix.com
http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
