[PEP 224] Attribute Docstrings

[David Goodger]

Some comments:

1. I think the idea of attribute docstrings is a great one. It would assist
in the auto-documenting of code immeasurably.

2. I second Frank Niessink (frankn=nuws at cs.vu.nl), who wrote:

> wouldn't the naming
> scheme <attributename>.__doc__ be a better one?
> 
> So if:
> 
> class C:
>   a = 1
>   """Description of a."""
> 
> then:
> 
> C.a.__doc__ == "Description of a."

'C.a.__doc__' is far more natural and Pythonic than 'C.__doc__a__'. The
latter would also require ugly tricks to access.

3. However, what would happen to C.a.__doc__ (or C.__doc__a__ for that
matter) when attribute 'a' is reassigned? For example:

    class C:
        a = 1  # class attribute, default value for instance attribute
        """Description of a."""

        def __init__(self, arg=None):
            if arg is not None:
                self.a = arg  # instance attribute
            self.b = []
            """Description of b."""

    instance = C(2)

What would instance.a.__doc__ (instance.__doc__a__) be? Would the __doc__ be
wiped out by the reassignment, or magically remain unless overridden?

4. How about instance attributes that are never class attributes? Like
'instance.b' in the example above?

5. Since docstrings "belong" to the attribute preceeding them, wouldn't it
be more Pythonic to write:

    class C:
        a = 1
            """Description of a."""

? (In case of mail viewer problems, each line above is indented relative to
the one before.) This emphasizes the relationship between the docstring and
the attribute. Of course, such an approach may entail a more complicated
modification to the Python source, but also more complete IMHO.

6. Instead of mangling names, how about an alternative approach? Each class,
instance, module, and function gets a single special name (call it
'__docs__' for now), a dictionary of attribute-name to docstring mappings.
__docs__ would be the docstring equivalent to __dict__. These dictionary
entries would not be affected by reassignment unless a new docstring is
specified. So, in the example from (3) above, we would have:

    >>> instance.__docs__
    {'b': 'Description of b.'}
    >>> C.__docs__
    {'a': 'Description of a.'}

Just as there is a built-in function 'dir' to apply Inheritance rules to
instance.__dict__, there would have to be a function 'docs' to apply
inheritance to instance.__docs__:

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


In conclusion, although this proposal has great promise, it still needs
work. If it's is to be done at all, better to do it right.

This could be the first true test of the PEP system; getting input from the
Python user community as well as the core PythonLabs and Python-Dev groups.
Other PEPs have been either after-the-fact or, in the case of those features
approved for inclusion in Python 2.0, too rushed for a significant
discussion.

-- 
David Goodger    dgoodger at bigfoot.com    Open-source projects:
 - The Go Tools Project: http://gotools.sourceforge.net
 (more to come!)