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

[Philipp von Weitershausen]

Stephan,

I share your concerns about the scrutability of the Zope 3 API. We 
certainly would not want to end up at a state where zope.app becomes 
this mystical place where all the magic happens (to unexperienced 
developers, at least).

Because of the configurability of components, global and local, I think 
it would not make much sense to use a filesystem-based tool that 
harvests all adapters, interfaces, etc. Especially with adapters and 
views, you would probably be more interested in what views are available 
for a certain object (or the interfaces this object implements) at 
runtime (or debugging time). That would greatly depend on local 
definitions as well. That again would not be covered by some filesystem 
utility putting together documentation based on ZCML configuration in 
zope.app...

I would suggest a tool similar to Dieter Maurer's DocFinder for Zope 2 
(http://www.dieter.handshake.de/pyprojects/zope/DocFinder.html). As you 
already suggested, the Intrspector is the right step in that direction. 
I guess the Introspector or the views on the InterfaceService could be 
extended to list available adapters and views for certain interfaces. 
Maybe there's a better place for this; all I'm saying is that the 
information should be gained dynamically at runtime (or, again, at 
debugging time).

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

+1 (the Introspector could ask the next available utility service or 
SiteManager whether registrations exists).

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

I guess here the Intrspector should be extended. It could look whether 
it is actually dealing with a content component and then display more 
information, such as the following:

> 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

+1e24

ForbiddenAttributeErrors could be prevented easily in advance, or at 
least be understood better with some interface that shows you security 
declarations. Again, that only makes sense at runtime.

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

IIRC, Jim wants to make changes to this or other machinery to allow us 
to list available registrations, be it views or adapters.

Philipp