[Python-Dev] Re: [PEP 224] Attribute Docstrings

[Christian Tanzer]

"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