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

M.-A. Lemburg mal@lemburg.com
Mon, 14 Aug 2000 13:27:27 +0200

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/