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
--
http://mail.python.org/mailman/listinfo/python-list
