[Zope-dev] Interfaces, HelpSys and API documentation

[Yuppie]

Hi!


I'm currently digging into Zope coding conventions. And I can't find any 
guidance how to use Zope Interfaces for API documentation in Zope's 
online help system.

I found these related pages, but they are all out of date:
<http://www.zope.org/Wikis/Interfaces/>
<http://www.zope.org/Members/michel/Projects/Interfaces/>
<http://dev.zope.org/Wikis/DevSite/Projects/APIDocs/>
<http://www.zope.org/DocProjects/zope_product>

The ZDG doesn't reflect the current API and mentions API help with just 
one word:
<http://www.zope.org/Documentation/Books/ZDG/current/ComponentsAndInterfaces.stx>
<http://www.zope.org/Documentation/Books/ZDG/current/Products.stx>


I think it is a Good Thing to use interfaces to generate API help, because
- using Interface.Verify you have a basic test if API documentation
    and implementation are in sync
- you don't have to write API documentation and Interfaces

But API Reference syntax and Interface syntax are not identical.

So far only some CMFCore interfaces follow this philosophy. (If you want 
to see a working example, look at WorkflowTool.py, 
interfaces\portal_workflow.py and tests\test_WorkflowTool.py)

But this example also shows the problem:
Reading the online API help, most people are interested in APIs they can 
use, not interface definitions. They are looking for 'portal_workflow', 
not 'WorkflowTool' or 'IWorkflowTool' or 'WorkflowToolInterface'.

In this example it is "solved" by using the same id for the interface 
and the unique object. The docstrings sometimes refer to "this tool" and 
sometimes to the "tool interface".


Did I miss some useful docs? Any ideas how to resolve this?

TIA,
Yuppie