[Zope-dev] Interfaces, HelpSys and API documentation
Yuppie
yuppie@zedat.fu-berlin.de
Sat, 23 Nov 2002 16:09:46 +0100
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