[Zope-dev] api docs [Was: Re: Post-mortem ...]

[Yuppie]

Hi!


Brian Lloyd wrote:
> Good call. I think it would be best to make sure the docstring of the 
> new method is clear on its reason for being. I think somewhere there 
> is an interface file that is used to generate some of the api docs - 
> ideally that can get updated too.

What is the Right Way to keep api docs in sync?


Example 1:

ZCatalog/IZCatalog.py seems to be more up to date, but 
ZCatalog/help/ZCatalog.py is used by the Zope Help System and I guess 
also to generate api docs.


Example 2:

I did add OFS/IOrderSupport.py, but how will it become part of help and 
api docs? Is there a better way than copying it to OFSP/help? I hate to 
add redundant code because - as example 1 shows - it is hard to keep the 
files in sync.


CMF uses the interface files also as help files. As interface files 
become more and more common in Zope it might make sense to do the same 
in Zope.


Cheers,
	Yuppie