[Zope] general API question

[Paul Winkler]

On Tue, Sep 28, 2004 at 07:21:43PM +0200, Dieter Maurer wrote:
> Paul Winkler wrote at 2004-9-27 19:57 -0400:
> > ...
> >      * check base classes for things that need documenting - either add 
> >        the base class to this API ref, or document any non-overridden 
> >        methods as part of the derived class docs - not sure how best 
> >        to do this so i'm handling it on a case-by-case basis.
> 
> Many of the base classes are mostly internal.
> 
> I think, we do not need a complete reference.
> It would be Oracle like (this is my synonym for "almost unusable").

Thanks for the advice, I really do appreciate it -
might keep me from going overboard :-)
But while I agree that we don't need "complete",
we do need more than what the current API reference provides.
To pick a random example, CopySupport is completely
absent, and IMO that is not justifiable.
 
> IMO it is more valuable to document the most relevant classes (and
> their most relevant attributes and methods)
> with typical usage rather than document everything but only
> superficially.
> 
> I am still convinced that automatic documentation
> extraction tools (like "DocFinder") are better than
> manual documentation -- for everything other than the essential
> concepts and the overview how things play together.

Yes. I don't know if you've seen my long-term proposal:
http://dev.zope.org/Wikis/DevSite/Proposals/SanitizeHelpSysAndAPIReference

In that shiny sci-fi world, DocFinder would still be a great
way to explore the *implementation*, but we would also have
clear browsable documentation of the *interfaces*.
But this is an even bigger job than twiddling the current
API reference by hand, and I want the Zope Book to be better
ASAP.  Hence my decision to tackle the issue in stages.
My plan is that we'll first solve the immediate problem of there being
no good reference by getting urgent improvements into the Zope Book
first, and then fold the result of this work back in to
the source tree in the form of Interface docstrings.

Hopefully there will be community input along the way,
about what does and does not constitute API.
 
> >      It's a big job, best done one module at a time.
> 
> And keep in mind that it is not a one time job...

Well, if my plan succeeds, it is ;-)
 
> Every release is likely to change minor details.
> The more details you document now, the more details need
> checking for new releases.

I think I know what you're saying, but if I take this to
its logical conclusion, it means that there should be no
documentation at all.

> Do not do it!
> Document only the most essential classes (and how they fit with
> one another).

Thanks for the sanity check. But as already stated,
IMO "the most essential classes" includes a lot that is not
currently in the API ref.

Base classes are tricky.  I hate the "ObjectManagerItem" lie,
but I don't want to dive into all of SimpleItem's base classes. 
I started going down that road and I can see it
would be a disaster.

Maybe, some of these issues cannot be properly solved without 
diving into phase 2 of the plan and actually creating something like
an ISimpleItem interface. 
I might have to settle for a Zope Book 2.7 Appendix B that
is not as good as I'd like.

-- 

Paul Winkler
http://www.slinkp.com