New submission from Gregory P. Smith <g...@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 <rep...@bugs.python.org> <https://bugs.python.org/issue46349> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
