[Python-Dev] Doc-strings for class attributes ?!

[M.-A. Lemburg]

I've been doing a lot of auto-doc style documenation lately
and have wondered how to include documentation for class attributes
in a nice and usable way.

Right now, we already have doc-strings for modules, classes,
functions and methods. Yet there is no way to assign doc-strings
to arbitrary class attributes.

I figured that it would be nice to have the doc-strings for
attributes use the same notation as for the other objects, e.g.

class C
    " My class C "

    a = 1
    " This is the attribute a of class C, used for ..."

    b = 0
    " Setting b to 1 causes..."

The idea is to create an implicit second attribute for every
instance of documented attribute with a special name, e.g. for
attribute b:

    __doc__b__ = " Setting b to 1 causes..."

That way doc-strings would be able to use class inheritance
just like the attributes themselves. The extra attributes can
be created by the compiler. In -OO mode, these attributes would
not be created.

What do you think about this idea ?

-- 
Marc-Andre Lemburg
______________________________________________________________________
Business:                                      http://www.lemburg.com/
Python Pages:                           http://www.lemburg.com/python/