[Python-Dev] Re: [PEP 224] Attribute Docstrings (original) (raw)

Christian Tanzer tanzer@swing.co.at
Mon, 28 Aug 2000 18:27:44 +0200

"M.-A. Lemburg" <mal@lemburg.com> wrote:

> IMHO, David Goodger's (<dgoodger@bigfoot.com>) idea of using a > docs dictionary is a better solution: > =

> - It provides all docstrings for the attributes of an object in a > single place. > =

> * Handy in interactive mode. > * This simplifies the generation of documentation considerably. > =

> - It is easier to explain in the documentation =

The downside is that it doesn't work well together with class inheritance: docstrings of the above form can be overridden or inherited just like any other class attribute.

Yep. That's why David also proposed a doc' function combining the docs' of a class with all its ancestor's docs.

> Normally, Python concatenates adjacent strings. It doesn't do this > with docstrings. I think Python's behavior would be more consistent > if docstrings were concatenated like any other strings. =

Huh ? It does... =

>>> class C: _... "first line"_ ... "second line" ... =

>>> C.doc 'first linesecond line' =

And the same works for the attribute doc strings too.

Surprise. I tried it this morning. Didn't use a backslash, though. And al= most =

overlooked it now.

> > b =3D 2 > > > > def x(self): > > "C.x doc string" > > y =3D 3 > > return 1 > > > > "b's doc string" > > > > Since the definition of method "x" currently does not reset the=

> > used assignment name variable, it is still valid when the compi= ler > > reaches the docstring "b's doc string" and thus assigns the str= ing > > to doc_b. > =

> This is rather surprising behavior. Does this mean that a string in > the middle of a function definition would be interpreted as the > docstring of the function? =

No, since at the beginning of the function the name variable is set to NULL.

Fine. Could the attribute docstrings follow the same pattern, then?

> > A possible solution to this problem would be resetting the name=

> > variable for all non-expression nodes. > =

> IMHO, David Goodger's proposal of indenting the docstring relative to= the > attribute it refers to is a better solution. > =

> If that requires too many changes to the parser, the name variable > should be reset for all statement nodes. =

See my other mail: indenting is only allowed for blocks of code and these are usually started with a colon -- doesn't work here.

Too bad.

It's-still-a-great-addition-to-Python ly, =

Christian

-- =

Christian Tanzer tanzer@swing.co.= at Glasauergasse 32 Tel: +43 1 876 62 = 36 A-1130 Vienna, Austria Fax: +43 1 877 66 = 92