#29: Interfaces and Interface api documentation

Contents

1. Motivation
2. Proposal
3. Implementation

Proposed by

tiran

Proposal type

State

rejected

Motivation

Plone lacks a good api documentation of all essential tools and most tools can't be recognized using interfaces. Interfaces are one of the major improvements in zope 2.5 and especially in Zope3! Interfaces are used for documentation, unit testing [1] and asserting implementations [2].

Epydoc [3] is a great tool to generate api docs as html, latex and pdf. reST (restructured text) [4] is the successor of STX. Together they allow easy generation of api docs.

Proposal

• Documentation of all public methods of all tools used in Plone as interfaces:
  • Move all interfaces from CMF etc. to CMFPlone/interfaces resp. create interfaces for tools without an interface
  • Add doc strings with epydoc markup using reST to all public methods and classes
• Autogenerating api docs with epydoc

Implementation

• Move all interfaces to CMFPlone/interfaces resp add interfaces
• Check for missing methods and tools
• Change the doc strings using epydoc markup (see README-interfaces.txt for a markup guide)
• Generate API docs with epydoc