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

[Yuppie]

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.

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

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

- Some people don't write docstrings at all.

Why is this important?

- Writing and keeping up to date redundant documentation isn't cool, but 
some people might like to have useful docstring close to the 
implementation and not in an extra file.

- 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.



b) extracting documentation

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

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

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.


Just my 2 cents.
Cheers,

Yuppie