[issue40257] Improve the use of __doc__ in pydoc

[Serhiy Storchaka]

Serhiy Storchaka <storchaka+cpython at gmail.com> added the comment:

Inheritance of docstrings was added in issue15582. It works good for class members, but I now realized that doing it for class itself was a mistake. For example:

>>> import wave
>>> help(wave.Error)
Help on class Error in module wave:

class Error(builtins.Exception)
 |  Common base class for all non-exit exceptions.
 |  
 |  Method resolution order:
 |      Error
 |      builtins.Exception
 |      builtins.BaseException
 |      builtins.object
 |  
...

I fixed many similar issues by adding docstrings to classes, but there are even more exception classes and other classes in the stdlib for which help() gives incorrect description. I don't remember a single case when inheritance of the docstring was helpful.

Note that help() outputs the list of base class right after the docstring, so it is not hard to give an additional information, especially in interactive browser mode. If you want to inherit a docstring, you can do it explicitly:

    __doc__ = BaseClass.__doc__

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue40257>
_______________________________________