Feature request: Option to accept inherited docstrings

[torfsen]

Is this a BUG REPORT or FEATURE REQUEST?:

• bug
• feature

Description of Bug or Feature

Many tools (e.g. inspect.getdoc, Sphinx) allow methods in subclasses to inherit the docstring of the parent method:

class Foo:
    def do_it(self):
        """
        Do the thing!
        """
        pass

class SpecialFoo(Foo):
    def do_it(self):
        print('So special!')

In these cases, I usually only add a separate docstring to SpecialFoo.do_it if its behavior differs significantly from what one would expected after reading the docstring of Foo.do_it. In most cases, the docstring of Foo.do_it is just fine.

Hence I'd like an option to not count these cases as missing.

[econchick]

Hmm interesting thought. I'm going to have to investigate this a bit; it's weird that help(ChildClass.overwritten_method) shows the docstring of the parent class, but ast.get_docstring does not.

I'll get back to you - thanks for the idea!

[J08nY]

Hmm interesting thought. I'm going to have to investigate this a bit; it's weird that help(ChildClass.overwritten_method) shows the docstring of the parent class, but ast.get_docstring does not.

The way help() works is using pydoc which does its own search of the doc string. See: https://github.com/python/cpython/blob/63298930fb531ba2bb4f23bc3b915dbf1e17e9e1/Lib/pydoc.py#L185. There getdoc is called with the class as an argument. That further calls _getdoc which first tries _getowndoc which finds the docstring on the class itself and then _finddoc which looks through the superclasses in MRO (here) of the class and returns something. This could be also done in interrogate.

EDIT: Oh, so it seems this might not be so easy to add, as interrogate works on the ast level and does not really have access to the fully initialized classes, only their ast. To work it would have to somehow build the list of superclasses of a given class purely from the ast nodes it has seen (so this would likely need to be done as some sort of a post-processing step, after all nodes were processed), and then also include docstrings from classes outside of the analyzed code (libraries and stdlib) which would likely need to be imported. And in general this whole thing gets really tricky when working purely on the ast level, as the full superclass information is simply not there.