[Doc-SIG] suggestions for a PEP

Edward D. Loper edloper@gradient.cis.upenn.edu
Wed, 21 Mar 2001 13:35:24 EST

[On making docs deal with inheritance]

> >  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.
> I know I'm about to vary my tune but ... someone else has been talking
> persuasively out-of-band.  Rather than borrowing the doc directly off
> the parent ...

I think the issue of whether to borrow, or point back, etc., should
be one for the tools.  Which may be a good reason for the language
*not* to do anything automatic, like inheriting doc strings.  There
are similar questions about whether inherited methods should be listed
in a separate section or not, etc.

But at any rate, we should say that having f.__doc__=None indicates
that inheriting docs is acceptable, and f.__doc__='' means that
inheriting docs is not acceptable.

Of course, all of this will be difficult to do if we're
parsing the file instead of loading it as a module; but that's ok. :)