[ZDP] Zope is missing an API?

[Maik Roeder]

Hi Robb !

Robb Shecter wrote:
> But... the documentation seems, umm.. Perl-like.  I mean that in the
> best possible way.  :)  I really miss a totally hyperlinked,
> object-oriented API.

Well, as it currently stands, Digital Creations does not have the man power
to create such a beast.

> I picture something at least as good as the Python API docs, but
> maybe even up to the detailed level of the (automatically generated)
> Java API docs.

It would be great to have a good API documentation, and I think the 
Zope Quick Reference is already a good start. Much information is
stored in the Zope Source code, so maybe we can make a link to
the implementation of the methods described in the ZQR.

> To me, the goal of this is to help let the language stay simple, where
> the programmer consults an API for whatever libraries are needed -
> like Python and Java do it.

Keeping the language simple is up to Digital Creations. Discussion of
the API are possible on zope-dev mailing list.
 
> I had a down to earth problem where I really wished I had this:
> 
> I wanted to print a list of all the roles accessible to a certain
> script.  I quickly had lots of problems:
> 
> What methods are available in the current context?
> On what objects are the methods being invoked?
> How are the many getRole-like methods different from each other?
> (And, after finding a method)
> What is the class of the returned object?
> What attributes does it have?
> What methods does it have?
> I couldn't figure it out on my own, and got a DTML script from someone
> else.

The only way I keep myself informed about Zope is my vast collection
of Zope Snippets. Everytime I find a cool DTML script, I add it
to my collection, and when I want to know how to do a specific
thing that has to do with Roles for example, I do a search in
the snippet collection. When I find nothing appropriate, I look in
the ZQR. When I have a good search term like getRole, I may have 
a look in all the HowTos on the Zope homepage, and maybe look how
some other product handles the problem. If all fails, I usually
look into the Zope source code, and find out that I should have looked
there in the first place :-)

> So, concretely I want (and maybe others too?) an API that:
> 
> * Is hyperlinked
> * Shows all classes
> * Shows all methods both indexed alphabetically (practically how it is
> now), but also listed by class
> * All return values or interfaces of methods
> * Shows the inheritance hierarchy for each class
> * Shows all subclasses of any class
> 
> Now, due to the statically typed nature of Java, the Javadoc program
> can generate all of this automatically.  It then also defines special
> tags that programmers can use the documentation.   I don't how what
> this would be like with Zope.
> 
> Finally, I think there needs to be a clear document, in the PG, that
> clearly shows how an aribitrary method is invoked on an object, in the
> various contexts where this can be done in Zope.  This way,
> programmers can work in the "new" OO way of having a simple language,
> and a large library, instead of the "old" Perl way of having a large
> complex language with many parts that must be memorized.
> 
> OK, Just my 2 cents.  Again, I'm interested in helping with this, if
> others see some value in it.

I have added a project on the new ZDP site called 
"ZAPIDOC: Zope API Documentation Project".

There, I added your proposal. You can become a member of ZDP, and
the project is yours :-)

http://zdp.zope.org:8080/ZDP/projects/zapidoc/




Greetings,

Maik Röder