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

[M.-A. Lemburg]

Lately I was busy extracting documentation from a large
Python application. 

Everything worked just fine building on existing doc-strings and
the nice Python reflection features, but I came across one 
thing to which I didn't find a suitable Python-style solution:
inline documentation for class attributes.

We already have doc-strings for modules, classes, functions
and methods, but there is no support for documenting class
attributes in a way that:

1. is local to the attribute definition itself
2. doesn't affect the attribute object in any way (e.g. by
   adding wrappers of some sort)
3. behaves well under class inheritence
4. is available online

After some thinking and experimenting with different ways
of achieving the above I came up with the following solution
which looks very Pythonesque to me:

class C:
        " class C doc-string "

        a = 1
        " attribute C.a doc-string "

        b = 2
        " attribute C.b doc-string "

The compiler would handle these cases as follows:

" class C doc-string " -> C.__doc__
" attribute C.a doc-string " -> C.__doc__a__
" attribute C.b doc-string " -> C.__doc__b__

All of the above is perfectly valid Python syntax. Support
should be easy to add to the byte code compiler. The
name mangling assures that attribute doc-strings

a) participate in class inheritence and
b) are treated as special attributes (following the __xxx__
   convention)

Also, the look&feel of this convention is similar to that
of the other existing conventions: the doc string follows
the definition of the object.

What do you think about this idea ?

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