how to inherit docstrings?

[Carl Banks]

On Thursday, June 9, 2011 7:37:19 PM UTC-7, Eric Snow wrote:
> When I write ABCs to capture an interface, I usually put the
> documentation in the docstrings there.  Then when I implement I want
> to inherit the docstrings.  Implicit docstring inheritance for
> abstract base classes would meet my needs. 

Do all the subclasses do exactly the same thing?  What's the use of a docstring if it doesn't document what the function does?


class Shape(object):
    def draw(self):
        "Draw a shape"
        raise NotImplementedError

class Triangle(Shape):
    def draw(self):
        print "Triangle"

class Square(Shape):
    def draw(self):
        print "Square"

x = random.choice([Triange(),Square()])
print x.draw.__doc__  # prints "Draws a shape"


Quick, what shape is x.draw() going to draw?  Shouldn't your docstring say what the method is going to do?

So, I'm sorry, but I don't see this being sufficient for your use case for ABCs.


> I'm just not clear on the
> impact this would have for the other use cases of docstrings.

Whenever somebody overrides a method to do something different, the inherited docstring will be insufficient (as in your ABC example) or wrong.  This, I would say, is the case most of the time when overriding a base class method.  When this happens, the language is committing an error.

Put it this way: if Python doesn't automatically inherit docstrings, the worst that can happen is missing information.  If Python does inherit docstrings, it can lead to incorrect information.


Carl Banks