[Zope3-dev] interface implementation errors

[Martijn Faassen]

Guido Wesdorp wrote:
[generate documentation from interfaces only]

> Hmm... That would leave a gap in the (generated) documentation, stuff that is 
> important to know about but not defined in the interfaces (e.g. additional 
> 'public' methods on objects that use a general interface) will not be picked 
> up by the docgenerator... Of course I understand that not all members of an 
> object should be documented, but I'd like to have a way of generating docs 
> that do show (at least) all stuff that should be. Wouldn't it be an idea to 
> skip 'protected' and 'private' members instead?

Wouldn't it be possible to create a derived interface for those particular
objects which documents those apparently important public methods? I 
think following that pattern would be a good one -- this interface may
be special now, but may become more generally used tomorrow. And if not,
which is surely a common case too, it's not the worst way to write
documentation anyway. Zope 2's API documentation system actually works
with descriptions much like interfaces.

Regards,

Martijn