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:

The ZDG doesn't reflect the current API and mentions API help with just one word:

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?


Zope-Dev maillist - [EMAIL PROTECTED]
** No cross posts or HTML encoding! **
(Related lists - http://lists.zope.org/mailman/listinfo/zope-announce
http://lists.zope.org/mailman/listinfo/zope )

Reply via email to