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

Christian Tanzer tanzer@swing.co.at
Tue, 29 Aug 2000 08:42:17 +0200

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

> > > IMHO, David Goodger's (<dgoodger@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 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 thi= s > > > with docstrings. I think Python's behavior would be more consiste= nt > > > 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. An= d 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: =2E.. ("first line" =2E.. "second line") =2E.. =

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@swing.co.= at Glasauergasse 32 Tel: +43 1 876 62 = 36 A-1130 Vienna, Austria Fax: +43 1 877 66 = 92