Home Original page

how to inherit docstrings?

Carl Banks pavlovevidence at gmail.com
Thu Jun 9 23:36:53 EDT 2011 
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
More information about the Python-list mailing list