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:
> 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.
Zope-Dev maillist - [EMAIL PROTECTED]
** No cross posts or HTML encoding! **
(Related lists -