[Python-Dev] Re: [PEP 224] Attribute Docstrings (original) (raw)

David Goodger dgoodger@bigfoot.com
Sun, 27 Aug 2000 15:27:22 -0400

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@cs.vu.nl), who wrote:

wouldn't the naming scheme .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.

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

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

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

  1. 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@bigfoot.com Open-source projects: