[PEP 224] Attribute Docstrings
Christian Tanzer
tanzer at swing.co.at
Mon Aug 28 02:32:17 EDT 2000
"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.
> 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
> 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.
> 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?
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.
Hoping-to-use-attribute-docstrings-soon ly,
Christian
--
Christian Tanzer tanzer at swing.co.at
Glasauergasse 32 Tel: +43 1 876 62 36
A-1130 Vienna, Austria Fax: +43 1 877 66 92
More information about the Python-list
mailing list