[Zope-dev] Strange permissions in the (built-in) API reference

[Michel Pelletier]

Dieter Maurer wrote:
> 
> Recently, I read the "Interface Wiki". It covers most of
> the methods contained in the API and its permission descriptions
> made a very solid impression. Maybe, you can start from these
> descriptions.

The Interfaces Wiki is actually where all the API documention did come
from.  Are there inconsistencies?
 
> It might also not be optimal wrt. maintainability
> that the modules, their classes and their methods with
> the respective docstrings have been recreated
> just for API documentation purposes.
> Probably, it would be preferable to use the docstrings
> and the method prototypes from the source directly.
> You might still want to control with methods are described
> in the API and in which order.
> Personally, I would control this, too, inside the source
> documentation (a la javadoc), but I can imagine that an
> external configuration might be advantageous.

Yes, there are pros and cons on both sides, and Amos, Jim and I had some
long converstations about this very subject.  We decided to go with
seperate documentation instead of autogenerating it because:

1. An interface should be a contract, not just an artifact of the code.

2. Python, being without first class support for interfaces, has no
clear way of spelling an interface of a class.

3. Jim is working on formal interface support for python and he's
thinking hard about it, we definatly didn't want to think hard about it
and then turn out we came up with a bad answer, the existing API docs
are just that, docs, not interfaces.  When format interfaces come about,
API docs will probably be converted to that format.

Thanks for the comments!

-Michel