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

[M.-A. Lemburg]

David Goodger wrote:
> 
> 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.

Uhm, yes... that's what I wrote in the last paragraph.

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

I understand that you would rather like a "frozen" version
of the class docs, but this simply doesn't work out for
the common case of mixin classes and classes which are built
at runtime.

The name mangling is meant for internal use and just to give
the beast a name ;-) 

Doc tools can then take whatever action
they find necessary and apply the needed lookup, formatting
and content extraction. They might even add a frozen __docs__
attribute to classes which are known not to change after
creation.

I use such a function which I call freeze() to optimize many
static classes in my applications: the function scans all
available attributes in the inheritance tree and adds them
directly to the class in question. This gives some noticable
speedups for deeply nested class structures or ones which
use many mixin classes.

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

Sure, but let's do that in a doc() utility function.

I want to keep the implementation of this PEP clean and simple.
All meta-logic should be applied by external helpers.

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

Right, and that's why I'm proposing to use attributes for the
docstrings as well: the docstrings will then behave just like
the attributes they describe.

> The __doc__attribute__ name-mangling scheme strikes
> me as un-Pythonic, to be honest.

It may look a bit strange, but it's certainly not un-Pythonic:
just look at private name mangling or the many __xxx__ hooks
which Python uses.
 
> 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!

Thanks,
-- 
Marc-Andre Lemburg
______________________________________________________________________
Business:                                      http://www.lemburg.com/
Python Pages:                           http://www.lemburg.com/python/