[Python-Dev] Re: [PEP 224] Attribute Docstrings (original) (raw)

M.-A. Lemburg mal@lemburg.com
Mon, 28 Aug 2000 21:35:58 +0200

Christian Tanzer wrote:

"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.

The same can be done for doc__ style attributes: a helper function would just need to look at dir(Class) and then extract the attribute doc strings it finds. It could also do a DFS search to find a complete API description of the class by emulating attribute lookup and combine method and attribute docstrings to produce some nice online documentation output.

> > 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 almost overlooked it now.

You could also wrap the doc string in parenthesis or use a triple quote 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.

Fine. Could the attribute docstrings follow the same pattern, then?

They could and probably should by resetting the variable after all constructs which do not assign attributes.

> > > 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

Me thinks so too ;-)

-- Marc-Andre Lemburg

Business: http://www.lemburg.com/ Python Pages: http://www.lemburg.com/python/