how to inherit docstrings?

[Carl Banks]

On Friday, June 10, 2011 7:30:06 PM UTC-7, Steven D'Aprano wrote:
> Carl, I'm not exactly sure what your opposition is about here. Others 
> have already given real-world use cases for where inheriting docstrings 
> would be useful and valuable. Do you think that they are wrong? If so, 
> you should explain why their use-case is invalid and what solution they 
> should use.

I don't have any issue with inheriting docstrings explicitly.  Elsewhere in this thread I said I was +1 on the language helping to simplify this.  What I am opposed to automatically inheriting the docstrings.

I do think people are overstating the uses where inherited methods would share the same docstring, but that's besides the point.  Overstated or not, one cannot deny that the base method's docstring is frequently unacceptable for the derived method, and my opposition to automatic inheritance is because in those cases will lead to incorrect docstrings, and no other reason.

> If you fear that such docstring inheritance will become the default, 
> leading to a flood of inappropriate documentation, then I think we all 
> agree that this would be a bad thing.

That is exactly what I fear, and you are wrong that "we all agree that this would be a bad thing".  Several people in this thread are arguing that inheriting docstrings by default is the right thing, and that would lead to heaps of inappropriate documentation.


Carl Banks