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

[Christian Tanzer]

"M.-A. Lemburg" <mal at lemburg.com> wrote:

> > > > IMHO, David Goodger's (<dgoodger at bigfoot.com>) idea of using a
> > > > __docs__ dictionary is a better solution:
(snip)
> > > 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.

Of course, one can get at all docstrings by using `dir'. But it is a
pain and slow as hell. And nothing one would use in interactive mode.

As Python already handles the analogous case for `__dict__' and
`getattr', it seems to be just a SMOP to do it for `__docs__', too. 

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

Wrapping a docstring in parentheses doesn't work in 1.5.2:

Python 1.5.2 (#5, Jan  4 2000, 11:37:02)  [GCC 2.7.2.1] on linux2
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>> class C:
...   ("first line"
...    "second line")
... 
>>> C.__doc__ 
>>> 

Triple quoted strings work -- that's what I'm constantly using. The
downside is, that the docstrings either contain spurious white space
or it messes up the layout of the code (if you start subsequent lines
in the first column).

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