[Python-Dev] Attribute docstrings [was: One-line abstractmethod function?]

[Stephen J. Turnbull]

Reply-To set to python-ideas at python.org.

Terry Reedy writes:

 > For data attributes, which are usually mutable, it should be attached to 
 > the attribute *concept*, which is represented by the name, rather than 
 > the current but usually changeable value. Values are usually already 
 > documented either by a value representation or a docstring. This could 
 > be done with a string subclass that is used as needed.
 > 
 > For methods, the value is nearly always constant. When multiple methods 
 > share the same function, they usually also share the same name, and 
 > represent the same concept.

Aside: Properties are which?  Data, or method?  It's also not clear to
me that "def first (self): return self.values[0]" is unlikely to be
used for completely different purposes than getting the head of a
list.  I conclude the considerations above are mostly red herrings.

The important thing, I suppose, is that the names of attributes
defined in a class are not mutable.  This means that their docstrings
can be kept in a completely separate dict (or other string -> string
mapping), which could even be stored in a separate file.  (Emacs Lisp
uses this to good effect.  The DOC file for XEmacs is 1.6MB; for GNU
Emacs it's 2.4MB.)  Of course it has its problems, but they're pretty
minor.