On Sun, Apr 04, 2004 at 05:06:52PM -0400, Chris McDonough wrote:
The "objects must have a docstring to be publishable" misfeature works against us here too if you want to get docs from code.
But that would be a non-issue if I create interfaces, right?
... 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.
granted.
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.
mm, you might have a point there. I'll change the proposal accordingly.
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)
why is killing the current help system necessary? I was thinking of keeping it but having it use docs from these proposed interfaces. -- Paul Winkler http://www.slinkp.com Look! Up in the sky! It's POTATO-FRY COOK! (random hero from isometric.spaceninja.com)