On Sun, 2004-04-04 at 15:20, 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. and maybe make it a bit easier for zope newbies to explore the codebase. "I grepped for ObjectManagerItem but it doesn't seem to exist" :-( But I tend to agree that Interfaces are the Right Thing here and would make it easier to extract docs.
The "objects must have a docstring to be publishable" misfeature works against us here too if you want to get docs from code. There are many things that are not web-callable that are part of the API. Making interfaces does seem like the "right thing". It also implies that whoever does it knows what the interfaces *are*, which is a subjective issue itself. Right now, the help system "interfaces" are completely ignored (by everyone except those who need it most: people who first come to Zope). Marking up Zope classes with interfaces is a really huge task because it will lead to many dark alleyways of Zope history and will undoubtedly lead to siutations of "I wanna change this because it's too embarrassing/complex to document". That said, if it could be done maybe one module at a time, it's a doable task I think. Maybe use short-lived "interface-markup" branches for each Zope module. Just pick a module to mark up with interfaces, make the branch, do the interfaces, ask for comments on maillists, and merge. Wash, rinse, repeat for each module. It will take a long time, but at least it would be in-progress. Dealing with the presentation aspect (which IMHO involves killing the help system and replacing it with simple files on a filesystem or chapters in an online book) could be dealt with when the interfaces are complete (which may be never, but that's really ok).
:-)
if we can safely assume that zope 2 is going to have a useful life measured in years from today, I think the task is worthwhile. I've seen a few of these "hurt^H^H^H^Hhelp" jokes lately, and the user comments on the online API reference are rather grim.
Yes, it's definitely a weak spot.
Yes, those are in there along with many other standard Products. The current set of modules listed in the API reference are:
AccessControl AuthenticatedUser DTMLDocument DTMLMethod DateTime ExternalMethod File Folder Image MailHost ObjectManager ObjectManagerItem PropertyManager PropertySheet PropertySheets PythonScript Request Response SessionInterfaces TransienceInterfaces UserFolder Vocabulary ZCatalog ZSQLMethod ZTUtils math random sequence standard string
This is somewhat misleading as File is not a module and ObjectManagerItem is completely fictitious. There may be other such "helpful" inaccuracies.
There are probably a bunch of things missing from that list too. E.g. OFS.Cache.* comes to mind.
Yeah. The list has grown, but the docs haven't kept up. - C