"M.-A. Lemburg" <mal@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 =3D 1
> "attribute C.a doc-string (1)"
> =
> b =3D 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@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 =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 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 =3D 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@swing.co.=
at
Glasauergasse 32 Tel: +43 1 876 62 =
36
A-1130 Vienna, Austria Fax: +43 1 877 66 =
92
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4