[Doc-SIG] suggestions for a PEP
Edward D. Loper
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. :)