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)? Jean-Paul _______________________________________________ Twisted-Python mailing list Twisted-Python@twistedmatrix.com http://twistedmatrix.com/cgi-bin/mailman/listinfo/twisted-python
