[Doc-SIG] documenting class attributes

[M.-A. Lemburg]

Edward Welbourne wrote:
> 
> Interesting.  I have one variety of class where I manage to do this, but
> it's not generally helpful ... in a base class, Lazy, an idiom is
> introduced where, for any 'name' not ending in an _ or starting with
> more than one _, a method called _lazy_get_name_ will be used to supply
> the value of name (the first time it's asked for: it's then stored in
> __dict__); this has become my standard way to document attributes
> (because, of course, I make attributes lazy wherever possible).  A few
> attributes get to be specified in __init__'s docs, because it's saying
> how it'll initialise them from its inputs.
> 
> But generally, the only way to document attributes is using a
> descriptive list in the class docstring ... which isn't
> > ... **adjacent to the entity documented** *and* user visible.
> but then I'm a bit skeptical about the line where it gets set being the
> right place to document it, if only because the attribute may get set in
> any method, so how do I know where to look for this line ...
> 
> In some sense, `adjacent to the entity' is meaningless for a python
> object's attributes, the best you can do is `adjacent to a line of code
> which happens to set it' or similar.  (If not, please illustrate.)
> 
> The other `solution' I've used (in places) is to have the attribute
> actually be a sophisticated object carrying around a doc string but
> managing to pretend to be the value we wanted for the attribute; again,
> not generally workable.
> 
> The right place for attribute description is in the typedef, and python
> doesn't make us do those; which only really leaves the class docstring.
>
> 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.
 
PEP 224 tried to address this problem. The good thing about the
solution proposed in PEP 224 is that it doesn't break any
working code and uses the same intuitive syntax as class doc-strings
themselves. Still, it was rejected, so I'm not trying to get that
approach into the core anymore.

If anybody has a better idea, please speak up...

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