Terry J. Reedy <[email protected]> added the comment:
Whether or not an object has a docstring is implementation defined, and I do
not consider it to be part of its API. I just backported some new docstrings
(with Brett Cannon's concurrence), and I would consider it OK for Serhiy to do
the same with his addition.
But the return value of getdoc is half of its API. Its 3.8 doc says
"If the documentation string for an object is not provided and the object is a
class, a method, a property or a descriptor, retrieve the documentation string
from the inheritance hierarchy.
Changed in version 3.5: Documentation strings are now inherited if not
overridden."
While inherited class docstrings are sometimes inapplicable, they may not be.
In any case, not doing so is an API change. If done, and this is obviously
controversial, the change needs a deprecation period. I would say at least 2
releases. And this should be a separate issue. But I suggest leaving getdoc
alone. I think it appropriate that it be a bit liberal in returning text that
just might be useful.
Changing what pydoc does with the information it gets, including from getdoc,
is a different issue -- this issue. Pydoc could not call getdoc for classes,
or it could determine whether the returned string is inherited and change it
slightly as has been suggested.
Other object information functions can make their own choices. For instance,
IDLE calltips are primarily about signature and currently only use an object's
own docstring. But maybe pydoc should be used for instance methods to get the
one or two summary lines IDLE displays.
A related note: Useful specific docstrings would be easier if an object could
directly extend a base objects docstring with
f"{base_object.__doc__}\nExtra implementation info\n"
following the header instead of having to later write
derived_object.__doc__ = f"....".
In instructional contexts, this would be useful, in addition for classes, for
functions that implement a docstring specificaton.
def _factor(number):
"Return prime factors of non-negative ints as list of (prime, count) pairs."
Students could then submit an implementation with
def factor(number):
f"{_factor.__doc__}\nImplementation details."
<implementation code>
----------
nosy: +terry.reedy
_______________________________________
Python tracker <[email protected]>
<https://bugs.python.org/issue40257>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
