[Doc-SIG] suggestions for a PEP

Edward D. Loper edloper@gradient.cis.upenn.edu
Sun, 18 Mar 2001 20:41:47 EST

Eddy, re. the issue of inheriting docstrings for methods from
base classes, said:

>> I'd solidly prefer to require an empty doc-string in a method which
>> doesn't want to inherit the doc-string of its parent.  

I tend to agree; but it seems from Guido's mail like this isn't 
anything that's likely to happen soon.  So I propose the following:
  1. For now, do *not* recommend that people use::

        f.__doc__ = parent.f.__doc__

  2. For now, recommend that *tools* inherit documentation for a
     method if f.__doc__ == None, and don't inherit if 
     f.__doc__ = '' or any other string.

  3. We can discuss writing a PEP, separate from all the docstring
     issues we're currently discussing, to handle inheritance of

  4. If/when such a PEP goes through, the tools could optionally
     be simplified, but nothing will break (because now the doc
     strings of the methods in question won't be None anymore).

Sound reasonable?