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

[M.-A. Lemburg]

Christian Tanzer wrote:
> 
> "M.-A. Lemburg" <mal at lemburg.com> wrote:
> 
> >     This PEP proposes a small addition to the way Python currently
> >     handles docstrings embedded in Python code.
> (snip)
> >     Here is an example:
> >
> >         class C:
> >             "class C doc-string"
> >
> >             a = 1
> >             "attribute C.a doc-string (1)"
> >
> >             b = 2
> >             "attribute C.b doc-string (2)"
> >
> >     The docstrings (1) and (2) are currently being ignored by the
> >     Python byte code compiler, but could obviously be put to good use
> >     for documenting the named assignments that precede them.
> >
> >     This PEP proposes to also make use of these cases by proposing
> >     semantics for adding their content to the objects in which they
> >     appear under new generated attribute names.
> 
> Great proposal. This would make docstrings even more useful.

Right :-)
 
> >     In order to preserve features like inheritance and hiding of
> >     Python's special attributes (ones with leading and trailing double
> >     underscores), a special name mangling has to be applied which
> >     uniquely identifies the docstring as belonging to the name
> >     assignment and allows finding the docstring later on by inspecting
> >     the namespace.
> >
> >     The following name mangling scheme achieves all of the above:
> >
> >         __doc__<attributename>__
> 
> IMHO, David Goodger's (<dgoodger at 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.
 
> >     To keep track of the last assigned name, the byte code compiler
> >     stores this name in a variable of the compiling structure.  This
> >     variable defaults to NULL.  When it sees a docstring, it then
> >     checks the variable and uses the name as basis for the above name
> >     mangling to produce an implicit assignment of the docstring to the
> >     mangled name.  It then resets the variable to NULL to avoid
> >     duplicate assignments.
> 
> 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.

> >     Since the implementation does not reset the compiling structure
> >     variable when processing a non-expression, e.g. a function
> >     definition, the last assigned name remains active until either the
> >     next assignment or the next occurrence of a docstring.
> >
> >     This can lead to cases where the docstring and assignment may be
> >     separated by other expressions:
> >
> >         class C:
> >             "C doc string"
> >
> >             b = 2
> >
> >             def x(self):
> >                 "C.x doc string"
> >                 y = 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 compiler
> >     reaches the docstring "b's doc string" and thus assigns the string
> >     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.
 
> For instance,
> 
>     def spam():
>         a = 3
>         "Is this spam's docstring? (not in 1.5.2)"
>         return 1
> 
> Anyway, the behavior of Python should be the same for all kinds of
> docstrings.
> 
> >     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.

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