[Doc-SIG] documenting class attributes

[M.-A. Lemburg]

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.

Some issues:

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
   class doc-string

> > 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 ?

-- 
Marc-Andre Lemburg
______________________________________________________________________
Company & Consulting:                           http://www.egenix.com/
Python Pages:                           http://www.lemburg.com/python/