[Doc-SIG] documenting class attributes
Mon, 26 Mar 2001 11:26:05 +0200
Edward Welbourne wrote:
> >> What's wrong with the class docstring ?
> > It doesn't support class inheritance, that is overriding attributes
> > with new meanings does not work and you also have to chance to
> > build a complete list of all interface attributes.
> but, if Tony and Edward manage to formalise the structure of the class
> docstring enough that it has an attributes section, tools can auto-trawl
> base classes to achieve these desiderata. Each class effectively
> supplies a mapping from names of attributes it defines to attribute
> docstrings (extracted from the class' description of the attribute);
> judicious munging and mangling should then suffice to build up, for each
> class, a mapping from names of attributes it has (whether it defines
> them, redefines them or just inherits them) to their docstrings.
> Job Done.
1. the documentation is separated from the attribute
definition -- minor issue, but still important (methods are
not documented in the class doc-string either)
2. you'll have to reformat all class doc-strings to make the new
feature available (I think common use is to simply add hash
comments just before or after the attribute definitions -- these
should be easily reusable)
3. we'd need a runtime tool to extract the information from the
> > If anybody has a better idea, please speak up...
> will the above do ?
> If not, why not ?
> I mean, aside from depending on a suitably well-formalised and widely
> used `Attributes:' section in the class doc-string, and the possibility
> of the whole ST project being torpedoed by Guido ...
I wasn't under the impression that Guido was trying to torpedo
the ST approach. Where did you get that idea ?
Company & Consulting: http://www.egenix.com/
Python Pages: http://www.lemburg.com/python/