On Tue, Nov 11, 2003 at 04:40:08PM +0100, Andreas Jung wrote:
--On Dienstag, 11. November 2003 10:24 Uhr -0500 Paul Winkler <pw_lists@slinkp.com> wrote:
On Tue, Nov 11, 2003 at 12:40:45AM -0800, Dennis Allison wrote:
Please take a look at The Zope Book (2_6 Edition). The Appendices contain the API for Zope. The book itself contains a wealth of infomration. The help files are another useful source of information. When all else fails, read the code.
The Zope API Reference, useful as it is, is far from complete. For example, it does not answer the O.P.'s question.
This raises my old question: why aren't there people in the community willing to contribute to the documentation? Other projects have less problems in producing a reasonable up-2-date documentation. It is only a problem of the Zope community? I really don't understand this...
We talked a bit about the API reference during the 2.6 Zope Book process. As I recall, the problems were partly logistical. the Zope Book has embedded comments, and we don't want to lose those. On the other hand, the API reference was IIRC originally generated from the Help system. So there's an impedance mismatch there. You don't want to make a change in the API reference without making the same change in the embedded docs; this requires developer access to the Zope sources. These problems are surely not insoluble, but nobody's had the time and/or drive to deal with it. Furthermore, it's rather odd that the embedded docs are only semi-embedded. What I mean is, they are not pulled from docstrings of the actual classes, but from separate files in the help/ directories scattered around the zope source tree, which can get out of sync with the real code. I guess this was done to allow developers a bit more leeway in what they do with their docstrings? Or to avoid cluttering up the API reference with stuff that is meant to be purely internal? But it leads to weird historical cruft like ObjectManagerItem (my favorite API reference gripe), an imaginary class that exists only in the docs. -- Paul Winkler http://www.slinkp.com Look! Up in the sky! It's PREDOMINANT SPAZ! (random hero from isometric.spaceninja.com)