[Python-Dev] Doc-strings for class attributes ?! (original) (raw)

M.-A. Lemburg mal@lemburg.com
Mon, 21 Aug 2000 22:22:10 +0200

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/