This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Author gregory.p.smith
Recipients gregory.p.smith
Date 2022-01-11.21:39:13
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1641937153.72.0.655254762095.issue46349@roundup.psfhosted.org>
In-reply-to
Content
Today `inspect.getdoc()` is quite simple. If a method has any docstring, it returns it.

There is one idiom where this is not very useful to our users.  A """See base class.""" docstring on a method.

Rather than having to repeat the canonical base class documentation in all methods or argue with tooling about not having a docstring in this common scenario, a single line docstring being used as a hint to just bring in the parent's docstring would be more helpful to the user.

Today's inspect.getdoc() could would turn from:
https://github.com/python/cpython/blob/main/Lib/inspect.py#L850

into something like:

```
    ...
    if doc is None or (isinstance(doc, str) and '\n' not in doc.strip()):
          try:
              parent_doc = _finddoc(object)
              if doc is None:
                  doc = parent_doc
              elif isinstance(parent_doc, str):
                  doc = f'{doc}\nParent class MRO doc:\n{parent_doc}'
          except (AttributeError, TypeError):
              return doc
   ...
```

Why not just tell people to omit docstrings when they want parent docs?  Because not all coding styles and linter tooling allows for this as they aim to enforce that documentation _is_ written.  Source analysis tooling and IDEs may not have a whole transitive dependency view of where the base classes even come from and are thus incapable of reliably analyzing whether a parent MRO method even exists or has a docstring.  This allows for trivial one line docstrings in that situation while still providing better information to the help() user.

This would add value to when using help(typical_subclass_of_abstract_thing.method) in notebooks.
History
Date User Action Args
2022-01-11 21:39:13gregory.p.smithsetrecipients: + gregory.p.smith
2022-01-11 21:39:13gregory.p.smithsetmessageid: <1641937153.72.0.655254762095.issue46349@roundup.psfhosted.org>
2022-01-11 21:39:13gregory.p.smithlinkissue46349 messages
2022-01-11 21:39:13gregory.p.smithcreate