[Zope3-dev] Re: Interface support in Python? (was Re: Proposal: Improving on __implements__)

[Jim Fulton]

Yuppie wrote:
> Jim Fulton wrote:
> 
>> I would love to see interfaces added to Python, assuming that they
>> are substantially similar to what we have now.  I'm not optimistic that
>> it will ever happen.  I'm convinced that it won't happen if I'm the
>> only one advocating it because:
>>
>> - It needs broad support for adoption, and
> 
> 
> Writing interfaces is an additional burden for coders, so I think you 
> have to focus on
> 
> - making usage of interfaces as easy as possible
> 
> - rewarding coders for their work
> 
> 
> One thing I think is really cool is the way interfaces could help you 
> writing API documentation and keeping it up to date.
> 
> But this feature isn't mature at all:
> 
> 
> 
> a) writing documentation
> 
> What is the relationship between the docstring of the implementation and 
> the documentation in the interface?
> 
> - Some people add information specific to the implementation to the 
> docstring.

I think this is reasonable if the implementation adds semantics beyond those
described in the interface.

> - Some people just copy the interface definition to the docstring of the 
> implementation.

This is a bad idea if the copying is done at the source level.
It would be nice if there was a nice way to do this.  One way is:

class F:
   __implements__ = IFoo

   def m(self):
      ....

   m.__doc__ = IFoo['m'].__doc__

but this is a bit cumbersome.

It also doesn't help the person reading the source.

> - Some people write 'see interface' into the docstring.

Of course, this isn't very satisfying. :)

> - Some people don't write docstrings at all.

This is probably the sanest approach. :)

> Why is this important?
> 
> - Writing and keeping up to date redundant documentation isn't cool,

Right. In fact, it can be worse than not cool. If the interface
changes and you forget to update the implementation doc strings, then
you have wrong documentation, which is worse than no documentation.

 > but
> some people might like to have useful docstring close to the 
> implementation and not in an extra file.

True.  This is a case where it's really hard to make everyone happy.

> - Extracting documentation becomes difficult if there are no rules. We 
> don't want to have redundant information in the documentation, but if 
> the docstring contains additional information we want to integrate it in 
> the API documentation.

Yup.

> 
> 
> b) extracting documentation
> 
> In Zope2 API help generated from interfaces isn't very useful, because 
> it shows only definitions, not implementations.

yes.

> In Zope3 there is the introspector, but this is just alpha.

Of course. This would be a nice project for someone to pick up
and run with.

> It should be fun browsing the documentation based on interfaces and 
> exporting it to any format. If this would be integrated in all kind of 
> documentation utilities, cvs web interfaces and IDEs, that would be 
> really cool.

Yes it would.

BTW, Holger Krekel wrote some nice tools in Rotterdam for browsing
interfaces and documentation. When you asked for the documentation of an object,
it showed the documentation defined in the interfaces.

It's relatively straightforward making interface documentation work well
in an object browsing environment,

Source browsing is much harder.  I suspect some sort of "See interface ...."
is best when browsing sources.

Jim

-- 
Jim Fulton           mailto:jim@zope.com       Python Powered!
CTO                  (888) 344-4332            http://www.python.org
Zope Corporation     http://www.zope.com       http://www.zope.org