[Doc-SIG] documenting class attributes

[Edward Welbourne]

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 ?

	Eddy.