Author serhiy.storchaka
Recipients gvanrossum, levkivskyi, ncoghlan, serhiy.storchaka, veky, yselivanov
Date 2020-04-12.09:27:18
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1586683639.13.0.935800516029.issue40257@roundup.psfhosted.org>
In-reply-to
Content
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__
History
Date User Action Args
2020-04-12 09:27:19serhiy.storchakasetrecipients: + serhiy.storchaka, gvanrossum, ncoghlan, yselivanov, veky, levkivskyi
2020-04-12 09:27:19serhiy.storchakasetmessageid: <1586683639.13.0.935800516029.issue40257@roundup.psfhosted.org>
2020-04-12 09:27:19serhiy.storchakalinkissue40257 messages
2020-04-12 09:27:18serhiy.storchakacreate