[Zope-dev] [Announce] API Documentation Fishbowl Project

[Dan L. Pierson]

--On Wednesday, June 06, 2001 11:57:06 AM -0400 Paul Everitt 
<paul@digicool.com> wrote:

>
> Hmm, I'm surprised that 2 days has passed with no comment from zope-dev
> and no comments in the Wiki.  I hear constant complaints about lack of a
> polished API.  I expected this post to generate lots of interest.

I read it over, the final design seems acceptable if docs are actually 
written to it.

My main concern is the one that Chris McDonough expressed in great detail 
in the wiki, namely that definining the (existing) interfaces is THE 
critical step.  Simply documenting all of the methods of objects is not 
sufficient because it says nothing about which are important, which are 
internal only, which are obsolete, how they interact, etc.

The final design does base the API on hand-written interfaces, which is 
good.  There is also some seemingly fuzzy plans to have an interface 
verification tool, which will be of some value in catching some cases of 
non-compliance.  However, the vital hard bit of creating the hand-written 
interfaces and ensuring that they're right is sort of glossed over in my 
opinion.

I thought of adding some of this to the wiki, but it all seemed to amount 
to a redundant "me too" and I wasn't sure where to put it :-(

Following the spec for newly written products should be easier.  The CMF 
seems to me to be a good example of a product that has done so (though the 
interfaces seem to be getting out of date at the moment).  I have found 
online CMF API docs useful in practice.

Dan Pierson