On Nov 15, 2012, at 3:48 AM, exar...@twistedmatrix.com wrote: > On 08:03 am, 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.) > > 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 _______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
