[Zope] general API question

[Jim Anderson]

Paul and Dieter,

Combined, I feel you two have struck what I consider the most important 
points.
In his original response to me, Paul hit the nail on the head when he said
that the interface needs to be documented, meaning the public interface,
of course. Quite simply, if a class or method is in the public 
interface, it should be
documented. At this point, I'm not sure who decides if a method or
class is public or not, but I'll learn as I go forward.

I agree with Dieter that the API documentation should be
generated automatically.

Jim

Paul Winkler wrote:

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