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

[Paul Winkler]

On Sun, Apr 04, 2004 at 01:56:21PM -0400, Chris McDonough wrote:
> I'm not sure there is a rationale, other than it was composed before
> Interfaces existed and the "thing to do" at the time was to create docs
> that went into the hurt^H^H^H^Hhelp system.  I think the "real" answer
> would be to go and create interfaces for all API classes and turn that
> into an API reference (assuming people would update the interfaces when
> they updated the code.. but that's not a given either I guess).

yes, that is a risk. OTOH that's true of the current situation 
anyway.

>  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.

> but then again, I don't want to
> get in your way if you want to spend time on this godforsaken task.

:-) 

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.

 
> Adding insult to injury, I can't seem to get to zope.org... at least
> each request takes more than an embarrassing 10 seconds, and I'm way too
> impatient to wait for it, so I can't verify that the  real"API
> reference" doesn't span more than the OFS help system docs.  I think it
> may... IIRC DateTime, ZCatalog, and others are a part of the API
> reference.

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.

-- 

Paul Winkler
http://www.slinkp.com
Look! Up in the sky! It's ULTRA SINGLE MOTHER SPOOK!
(random hero from isometric.spaceninja.com)