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

[Chris McDonough]

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