[Zope] general API question

[Dieter Maurer]

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

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.

>      It's a big job, best done one module at a time.

And keep in mind that it is not a one time job...

Every release is likely to change minor details.
The more details you document now, the more details need
checking for new releases.

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

Reject any request for a complete documentation.
Link to automatic documentation extraction tools ("happydoc", "epidoc",
"DocFinder") for people that want more details....

-- 
Dieter