New submission from Serhiy Storchaka <storchaka+cpyt...@gmail.com>:
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. ---------- components: Library (Lib) messages: 366220 nosy: gvanrossum, levkivskyi, ncoghlan, serhiy.storchaka, yselivanov priority: normal severity: normal status: open title: Improve the use of __doc__ in pydoc type: enhancement versions: Python 3.9 _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue40257> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
