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

David Goodger dgoodger@bigfoot.com
Mon, 28 Aug 2000 23:05:41 -0400

on 2000-08-28 15:35, M.-A. Lemburg (mal@lemburg.com) wrote:

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.

Using dir(Class) wouldn't find any inherited attributes of the class. A depth-first search would be required for any use of attribute docstrings.

From the Python library docs:

dir ([object]) 

... The list is not necessarily complete; e.g., for classes,
attributes defined in base classes are not included, and for
class instances, methods are not included. ...

This can easily be verified by a quick interactive session:

>>> class C:
...     x = 1
... 
>>> class D(C):
...     y = 2
... 
>>> D.__dict__
{'__module__': '__main__', '__doc__': None, 'y': 2}
>>> C.__dict__
{'__doc__': None, '__module__': '__main__', 'x': 1}
>>> dir(D)
['__doc__', '__module__', 'y']
>>> i = D()
>>> i.__dict__
{}
>>> dir(i)
[]

So there are no entries in i's dict. And yet:

>>> i.x
1
>>> i.y
2

The advantage of the doc__attribute name-mangling scheme (over docs dictionaries) would be that the attribute docstrings would be accessible from subclasses and class instances. But since "these attributes are meant for tools to use, not humans," this is not an issue.

Just to find all attribute names, in order to extract the docstrings, you would have to go through a depth-first search of all base classes. Since you're doing that anyway, why not collect docstrings as you collect attributes? There would be no penalty. In fact, such an optimized function could be written and included in the standard distribution.

A perfectly good model exists in dict and dir(). Why not imitate it?

on 2000-08-28 04:28, M.-A. Lemburg (mal@lemburg.com) wrote:

This would not work well together with class inheritance.

It seems to me that it would work exactly as does class inheritance, cleanly and elegantly. The doc__attribute name-mangling scheme strikes me as un-Pythonic, to be honest.

Let me restate: I think the idea of attribute docstring is great. It brings a truly Pythonic, powerful auto-documentation system (a la POD or JavaDoc) closer. And I'm willing to help!

-- David Goodger dgoodger@bigfoot.com Open-source projects: