Christian Tanzer wrote: > > "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 = 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@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/
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