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

[M.-A. Lemburg]

[Note: Please CC: all messages on this thread to me directly as I
 am the PEP maintainer. If you don't, then I might not read your
 comments.]

David Goodger wrote:
> 
> Some comments:
> 
> 1. I think the idea of attribute docstrings is a great one. It would assist
> in the auto-documenting of code immeasurably.

Agreed ;-)
 
> 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.

This doesn't work, since Python objects cannot have arbitrary
attributes. Also, I wouldn't want to modify attribute objects indirectly
from the outside as the above implies.

I don't really see the argument of __doc__a__ being hard to
access: these attributes are meant for tools to use, not
humans ;-), and these tools can easily construct the right
lookup names by scanning the dir(obj) and then testing for
the various __doc__xxx__ strings.
 
> 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?

See above. This won't work.
 
> 4. How about instance attributes that are never class attributes? Like
> 'instance.b' in the example above?

I don't get the point... doc strings should always be considered
constant and thus be defined in the class/module definition.
 
> 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.

Note that Python's indents block and these are always preceeded
by a line ending in a colon. The above idea would break this.

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

This would not work well together with class inheritance.
 
> 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.

We'll see whether this "global" approach is a good one ;-)
In any case, I think it'll give more awareness of the PEP
system.

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