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 _______________________________________________ Zope-Dev maillist - [EMAIL PROTECTED] http://mail.zope.org/mailman/listinfo/zope-dev ** No cross posts or HTML encoding! ** (Related lists - http://mail.zope.org/mailman/listinfo/zope-announce http://mail.zope.org/mailman/listinfo/zope )
