[Doc-SIG] documenting class attributes

[Edward Welbourne]

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

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

	Eddy.