[New-bugs-announce] [issue46349] inspect.getdoc() should append parent class method docs when encountering a local one line docstring

[Gregory P. Smith]

New submission from Gregory P. Smith <greg at krypto.org>:

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.

----------
components: Library (Lib)
messages: 410335
nosy: gregory.p.smith
priority: normal
severity: normal
stage: needs patch
status: open
title: inspect.getdoc() should append parent class method docs when encountering a local one line docstring
type: enhancement
versions: Python 3.11

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue46349>
_______________________________________