[Zope-dev] Reasons for the current API reference docs implementation?

[Chris Withers]

Paul Winkler wrote:
>> I'm not
>>sure that exposing the docstrings of the classes themselves would be
>>much better than the current situation,
> 
> well, it would arguably make it marginally more likely that the api 
> reference is updated when the code is updated.  

Indeed. I think using interfaces and docstrings would be good, as twisted does:
http://www.twistedmatrix.com/documents/current/api/index.html
http://www.twistedmatrix.com/documents/current/api/twisted.application.service.Service.html

Who knows, it might even result in some docstrings getting updated :-)

At worst, it'll mean that people don't have to update 3 sets of (what should be) 
identical documentation, as is currently the case...

cheers,

Chris

-- 
Simplistix - Content Management, Zope & Python Consulting
            - http://www.simplistix.co.uk