[Zope] general API question

[Dieter Maurer]

Paul Winkler wrote at 2004-9-29 21:24 -0400:
> ...
>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.

My favorite view is:

  We need good overview information: concepts, relations, major
  building blocks, good examples for the most relevant use cases.
  
  These things cannot be derived automatically.

  Detailed information should be derived automatically only,
  by documentation extraction tools like "DocFinder", "epydoc"
  or the Zope3 "ApiDocTool".

  That they can work well, good source documentation (docstrings)
  is essential -- and indeed it is not too bad, currently.

I already argued with one of the first authors of the Zope Book
and the online help content (Michael).
I could not convince him. But the current state of affairs
(outdated, incomplete, week online help) demonstrates that I was
right...


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

I did not read the proposal but followed the occurrences in the
mailing list.

Personally, I would go this route and would not try to complete
the API reference in the Zope Book.

This does not mean, that no work whatsoever should go into the API
reference: if something *really* important is missing, it should
be added. But, there are more important tasks than making it
100 per cent complete...

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

Are you sure?

An interface is nothing more than a collection of methods
(and maybe attributes). This meta information can be provided
by (attribute) annotations directly in the source. This
is much less work than documenting the interface relation
in e.g. a piece of documentation.
An automatic extraction tool can look at these meta information
attributes and present the available methods (and attributes)
accordingly.

You look at the result and maybe improve a few method docstrings.
This will help not only the documentation but source maintenance, too.

That's it.


Hopefully, future software evolution will follow your example
(and extend the meta information attributes accordingly)
and you will always have up to date reference information -- without
lots of manual work for any new release...

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

That's what I like to call the power of handling person.
Were I the handling person, I surely would proceed the other way round :-)

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

No documentation that can be extracted. Yes indeed!
You still need the big picture: principles, paradigms,
concepts, how fits everything together.

Take the Java documentation as an example: 90 per cent is
automatically extracted directly from the source via
JavaDoc.

-- 
Dieter