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

[David Goodger]

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

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:
 - The Go Tools Project: http://gotools.sourceforge.net
 (more to come!)