[Zope3-dev] Re: New Pyskel changes

[Guido van Rossum]

[SteveA]
> > I'd be in favour of a tool that could re-apply docstrings to code,
> > carefully changing "See Foo.Bar.Baz" style minimal docstrings into
> > full copies of the originals. I could then use the cross-reference
> > style during development, and switch to the full style once I'm
> > sure the interfaces are fixed.

But mindlessly reapplying the docstrings from the interfaces could
create docstrings that don't match the implementation.

Do interface docstrings really change all that much?

I would expect that a good implementor would change the implementation
docstring to add additional notes specific to the implementation.
After all different implementations of the same interface usually
differ in some aspect that is worth documenting, and even if there's
only one implementation it may have properties beyond those specified
by the interface.

I agree that the old situation is (marginally) better than the current
pyskel.py behavior, but still think that copying the docstrings to the
source would be an overall improvement.

--Guido van Rossum (home page: http://www.python.org/~guido/)