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

[M.-A. Lemburg]

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__<attrname>__ 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/