how to inherit docstrings?

[Carl Banks]

On Thursday, June 9, 2011 10:18:34 PM UTC-7, Ben Finney wrote:

[snip example where programmer is expected to consult class docstring to infer what a method does]

> There's nothing wrong with the docstring for a method referring to the
> context within which the method is defined.
> 
> > Whenever somebody overrides a method to do something different, the
> > inherited docstring will be insufficient (as in your ABC example) or
> > wrong.
> 
> I hope the above demonstrates that your assertion is untrue. Every
> single method on a class doesn't need to specify the full context; a
> docstring that requires the reader to know what class the method belongs
> to is fine.

It does not.  A docstring that requires the user to  to figure out that is poor docstring.

There is nothing wrong, as you say, incomplete documentation that doesn't say what the function actually does.  There's nothing wrong with omitting the docstring entirely for that matter.  However, the question here is not whether a programmer is within right to use poor docstrings, but whether the langauge would go out of its way to support them.  It should not.

There is one thing that is very wrong to do with a docstring: provide incorrect or misleading information.  So, despite having brought the point up myself, I am going to say the point is moot.  Even if it is absolutely desirable for a language to go out it's way to support incomplete docstrings, part of that bargain is that the language will go out of its way to support flat-out wrong docstrings, and that trumps any ostensible benefit.


Carl Banks