[Zope3-dev] Re: New Pyskel changes

[R. David Murray]

On Tue, 9 Jul 2002, Guido van Rossum wrote:
> > Hence "carefully" above. As in, only reapply docstrings when the
> > existing docstring for the method is "See Foo.Bar.Baz". Do not reapply
> > the docstring if it has been changed.
>
> That doesn't sound like "reapply" to me, but rather as a separate tool
> to finalize docstrings.  Fine with me, as long as I also have an
> option to finalize docstrings right away (which works better for my
> programming style).

+1 on both counts, but -1 on Guido's earlier desire to just copy
the docstrings in pyskel.  Interfaces *do* change, and if they change
seldom, that actually makes it worse since it makes it less likely
everyone using the Interface will remember to change their copies.
In other words, I'd prefer *not* to see copies of the Interface
doc strings in implemenation code *unless* the update tool exists.

It would be even nicer if the docstring could conventionally be
broken into its two parts (Interface and implementation) so that
the tool could (carefully) update the Interface part even on a
method that has had its docstring expanded with implementation
details.  Then, in addition, the tool could *report* when an Interface
doc string is being changed, which might clue the programmer in to
a need to review the implementation for compliance....

I think we may be getting close to Proposal time here <grin>.

--RDM