Author terry.reedy
Recipients gvanrossum, levkivskyi, lukasz.langa, mbussonn, ncoghlan, serhiy.storchaka, terry.reedy, veky, xtreak
Date 2020-05-16.00:45:13
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1589589913.55.0.0812805459164.issue40257@roundup.psfhosted.org>
In-reply-to
Content
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>
History
Date User Action Args
2020-05-16 00:45:13terry.reedysetrecipients: + terry.reedy, gvanrossum, ncoghlan, lukasz.langa, serhiy.storchaka, veky, levkivskyi, mbussonn, xtreak
2020-05-16 00:45:13terry.reedysetmessageid: <1589589913.55.0.0812805459164.issue40257@roundup.psfhosted.org>
2020-05-16 00:45:13terry.reedylinkissue40257 messages
2020-05-16 00:45:13terry.reedycreate