[Zope3-dev] Towards better API documentation...

[Stephan Richter]

Hello everyone,

I started thinking about developing a tool that will give us some better API 
documentation. As we all know, common Python documentation tools work not 
very well on Zope 3 code, because

(a) they do not handle interfaces.

(b) they are unaware of the component architecture, which provides useful 
information, such as adapters for a given interface.

First off, I am not so interested in discussing the output of the tool. I do 
not care whether it will generate static or dynamic HTML documentation, STX 
or LaTeX; in fact, I would like to do all combinations at some point.

Interface Documentation
-----------------------

The interface documentation is and will be the central point of the API 
documentation. However, I think the current introspector does not provide as 
much information as it could. Here is a list of pieces of information I would 
like to have (including existing ones)

1. Documentation of all attributes/properties and methods. The introspector 
currently does a good job with that.

2. What adapters exist for this interface. This is two-fold, as I want to ask

  (a) Give me all Adapters that that exist for this interface.

  (b) Give me all Adapters that provide this interface.

3. A list of views defined for this interface should be optionally included 
too.

4. Optionally have a line saying whether this interface is used as a service 
or utility.


Class Documentation
-------------------

I think the current version of the introspector does pretty good here with the 
standard API. More specific information, such security, views and so on are 
better placed into Content Component documentation, since it is not 
applicable to all classes.


Service Component Documentation
-------------------------------

This is simply a list of all available services by name and links to the 
characteristic interface.

Content Component Documentation
-------------------------------

A list of of all content components should be provided with the following 
info.

1. There should be a link to the class of the component.

2. Display factory information.

3. Display security information

4. Display views defined for the content.


Did I forget anything? 

While the information is available, it might not be accessible. I checked the 
Adapter Service, Factory Service and the Service Manager and they have 
methods to access information as we need them. The Presentation Service, on 
the other hand, has a totally useless (read broken) "getRegisteredMatching()" 
method that does not even have a "return" call. Other than that it does not 
allow us to look for all available views of an interface.

I'd appreciate any input you might have.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training