Author serhiy.storchaka
Recipients gvanrossum, levkivskyi, ncoghlan, serhiy.storchaka, yselivanov
Date 2020-04-11.20:54:38
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1586638478.83.0.463728061154.issue40257@roundup.psfhosted.org>
In-reply-to
Content
Currently pydoc outputs __doc__ for classes, functions, methods, properties, etc (using inspect.getdoc()). If the object itself does not have non-empty __doc__, it searches non-empty __doc__ in the class parenthesis (if the object is a class) or in the corresponding overloaded members of the class to which the object (method, property, etc) belongs.

There are several problems with this.

1. Using the docstring of a parent class is misleading in most classes, especially if it is a base or abstract class (like object, Exception, Mapping).

2. If the object does not have the __doc__ attribute, it inherits it from its class, so inspect.getdoc(1) returns the same as inspect.getdoc(int).

3. If the object has own docstring, but is not a class or function, it will be output in the section DATA without a docstring.

The following PR fixes these issues.

1. Docstrings for classes are not inherited. It is better to not output a docstring than output the wrong one.

2. inspect.getdoc() returns the object's own docstring.

3. Docstrings are always output for object with a docstring. See for example help(typing).

In future issues I'll make help(typing) even more informative.
History
Date User Action Args
2020-04-11 20:54:38serhiy.storchakasetrecipients: + serhiy.storchaka, gvanrossum, ncoghlan, yselivanov, levkivskyi
2020-04-11 20:54:38serhiy.storchakasetmessageid: <1586638478.83.0.463728061154.issue40257@roundup.psfhosted.org>
2020-04-11 20:54:38serhiy.storchakalinkissue40257 messages
2020-04-11 20:54:38serhiy.storchakacreate