Re: SAF's DocReader - different wheels

On Sunday, September 15, 2002, at 05:53 PM, Brent Cook wrote:

Plus I document the hell out of it, but it's not in PHPDoc because I wrote my own DocReader (as I call it) before PHPDoc was even around. No biggie.

Wow! I just checked out your SAF package, and the DocReader is terrific! I love how it generates docs on-the-fly, how _fast_ it is and the lack of ambiguity of the documentation language.

Thanks! I'm glad to know I'm not the only one who likes it. :) I feared that people would dislike the XML-based syntax, since it adds a lot of extra weight to the comments. The counter argument is that syntax highlighting keeps things legible even in pretty ugly code (which I'm told mine is not), and writing it is really a matter of copy/paste a lot of the time. And now look, even Microsoft adopted something similar with C#! I almost feel like a trend-setter for once. :)

Since you had prepared this system before PHPDoc, were you proposing it as a solution around the time that PEAR was approaching its genesis? If not, why not? I would consider using this system a great asset to PEAR. It seems more expandable, easily parsable and usable than PHPDoc today (not that the work gone into PHPDoc hasn't been appreciated). It probably could have gone either way when PEAR was begun regarding documentation standards and with everything else. Is it possible with PEAR now to say 'hmm, maybe we should try something different'? I really like this.

I don't think I was subscribed to the PEAR list at that time. I remember when PEAR was first announced and there wasn't much of a site together yet, I had other stuff to concentrate on so I put it in the bottomless bookmark pile and forgot about it for a while. I found it again eventually, but I think I came back too late for that discussion. Oops! If DocReader would be welcome in PEAR, then I have no problem with that. SAF uses the PHP license pretty much (might be Apache, can't remember), so there's no issue there either. I know DocReader relies on my own XML parser and document format, which are not at all DOM compliant (I figured why write another DOM layer in PHP when there's already a DOM extension that will stabilize eventually. So I wrote something that is more specific to my needs). I call the parser Sloppy, because the name used to describe it well. If DocReader was brought into PEAR, these could easily be replaced with PEAR equivalents, or Sloppy/XMLDoc could be brought into PEAR as well. The catch is that I won't have time to make this happen for quite a while. I'm on my last stretch with the 3.0 release of my software (including SAF), and then I've got a month of beta testing/guide & tutorial writing ahead of that (slated for all of October), then a month of promoting/making sales, then I'll be visiting my family for most of December, during which time I could probably start work on something like this. BTW, off topic, for Christian Stocker -- I'm very interested in your recently mentioned WebDAV server library, and as soon as I can/whenever I can, I would like to help out with that. I've read the WebDAV rfcs but I haven't touched on it at all from a coding standpoint. I haven't had a chance to check it out yet, but I had a thought that it would be nice to abstract the handling of the request so that different backends could be inserted like drivers. The filesystem is nice and all, but it would be way cool to be able to write a database backend as well (and specifically in my case, a db backend that could interact with my existing locking/versioning packages), or any other backend we could conceive and produce. Anyway, time for sleep. I mean, precious little time for sleep. :) Cheers, Lux

- Brent -- PEAR Development Mailing List (http://pear.php.net/) To unsubscribe, visit: http://www.php.net/unsub.php

-- John Luxford Simian Systems _______________________ phone : 204.946.5955 email : lux@simian.ca web : www.simian.ca _______________________ web content management application development consulting and training