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

[M.-A. Lemburg]

Aahz Maruch wrote:
> 
> [p&e]
> 
> In article <39AA22A0.D533598A at lemburg.com>,
> M.-A. Lemburg <mal at lemburg.com> wrote:
> >
> >>     >>> docs(instance)
> >>     {'a': 'Description of a.', 'b': 'Description of b.'}
> >>
> >> There are repercussions here. A module containing the example from (3) above
> >> would have a __docs__ dictionary containing mappings for docstrings for each
> >> top-level class and function defined, in addition to docstrings for each
> >> global variable.
> >
> >This would not work well together with class inheritance.
> 
> Could you provide an example explaining this?  Using a dict *seems* like
> a good idea to me, too.

class A:
    " Base class for database "

    x = "???"
    " name of the database; override in subclasses ! "

    y = 1
    " run in auto-commit ? "

class D(A):

    x = "mydb"
    """ name of the attached database; note that this must support
        transactions 
    """

This will give you:

A.__doc__x__ == " name of the database; override in subclasses ! "
A.__doc__y__ == " run in auto-commit ? "
D.__doc__x__ == """ name of the attached database; note that this must support
        transactions 
    """
D.__doc__y__ == " run in auto-commit ? "

There's no way you are going to achieve this using dictionaries.

Note: You can always build dictionaries of docstring by using
the existing Python introspection features. This PEP is
meant to provide the data -- not the extraction tools.

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