[CODE] Overridden method docstring

[kangz12345]

Problem

When a method is overridden, its docstring would contain duplicate information since the super class also has the docstring for the method. This makes the code management harder since we have to update the docstring everywhere. When any mistake happens, e.g., forgetting to update docstring somewhere, there exist multiple versions of docstrings. This will corrupt the repository very silently.

Suggestion

Keep only one original docstring in the super class. If a subclass overrides a method, write """Overridden.""" in its docstring. One may write additional information about additional features that are not intended by the super class (same for the arguments). For example:

class Foo:
    def foo(self, a, b=None):
        """Method foo.

        Args:
            a: Argument.
            b: Keyword argument.
        """

class Bar(Foo):
    def foo(self, a, b=()):
        """Overridden.

        It prints "bar".

        Args:
            b: An iterable.
        """
        print("bar")

When the method calls the super class version, i.e., super().method(...), write """Extended.""" rather than """Overridden.""". For example:

class Baz(Foo):
    def foo(self, a, b=None):
        """Extended.

        It prints "baz".
        """
        super().foo(a, b)
        print("baz")