Re: PHPDoc renderer not working

Greg, I will take a deep look (after the finals) inside both PHPDoc and PHPDocumentor. I don't know about Brent or Tim but but I'm pretty "neutral" in this case and I think that's a good thing. So I'll see what seems better in my opinion to keep in both and all we will discuss about it. My conclusions will be just technical and without any "evangelism" or something like that. =) My intention is to try to keep all aspects of both (if possible) and make a unified PHPDoc. So the user will have all the benefits of each one combined. The best thing is to join our skills, time and ideas and let the things flow. On Mon, 2002-04-29 at 14:08, Greg Beaver wrote: > Hello everyone, > > As a representative from the PHPDocumentor camp, I'd like to explain the > differences between our implementation and the pear PHPDoc, to see if you > are interested in trying to merge. If we can combine the best features of > each, I do think it would be beneficial for PHP, which is our primary goal > over here. > > PHPDocumentor uses an event-driven parser, designed by Joshua Eichorn, which > is faster than a grepper, more versatile, and in my opinion a brilliant > design. It's more modular, as it allows for a lookup function table, and is > easier to read at the source level. The event-driven parser also allows > PHPDocumentor to parse multiple elements in the same file, and to > differentiate between functions and methods. This feature is not as > important to PEAR folks since the spec requires each thing to be in its own > file, but most PHP projects already out there (and working nicely) are not > coded in that fashion (including mine, found as the backend at > http://calendar.chiaraquartet.net). In addition, the code is > more compact, > which makes updating simpler. > > Some of the features that the event-driven parser make possible include: > * ignoring @ if it isn't at the beginning of the line (as per JavaDoc spec) > * inline {@tags} like {@link} (as per JavaDoc) > * package-level docs (as per JavaDoc) > * easy extension of the parser for special-purpose projects (like the > package-page parser ppageParser) > * parsing of files with complicated quoting (single, double, perl-style <<<, > and escaped quotes) effortlessly > * easy addition of parser events for new language elements, without > modification to the previous code > > Some of the features that are our own preference: > * parsing into subdirectories by package and subpackage (as per JavaDoc), > also makes plugging into products > like Macromedia Homesite help system very convenient (that's my interest > :) > * element index by package as well as documentation-wide > * class trees by package > * very smart inheritance of variables and methods with complete overriding > understanding > * linking to anything under the sun (and smart linking - linking to > inherited methods by name searches the class > tree and links to the proper parent class file) > * document by package, specify page title. This is a simple way to ignore > files, and even elements in files, that > are irrelevant to a generated documentation. This also makes it possible > to generate documentation for > production release without modification > * detailed documentation of the PHPDocumentor tag specification, so that > people have some idea how to use > the thing who aren't already using it > > The direction PHPDocumentor would like to go is to be compatible with your > documentor so that people with code previously documented for the pear > PHPDoc will be able to migrate seamlessly (and the release 0.4.2 for later > today is nearly there, only missing a few important things). > > Things we'd like to see in future versions: > * doclet-style intermediate output, a data structure between parsing and > rendering that can be adapted to other > documentation formats (like PHPDoc xml output only a little more > flexible) > * makefile - save documentation in format described above along with file > modification information, speed up > repeat parsing of documentation > * more flexible templating - using the first feature described, design > engines that can convert the data to formats > needed by other template engines to allow complete customization of > output > * parser/linker error and warnings similar to PHPDoc's, that's real nice > * more attractive output for the aesthetically inclined, and easier > navigation of output > * other brilliant ideas that we mere mortals have not thought of > * see the sourceforge page http://www.sf.net/projects/phpdocu > for specific > features/bugs we're working on > > If this sounds like a direction that the PEAR PHPDoc folks would like to go, > we are very happy to attempt to combine forces. Basically, it would involve > dropping the grepper entirely, so if that is crucial, then we probably won't > see eye to eye. I would imagine that the integration won't be very smooth > until the doclet-style intermediate output feature described above is > implemented, which we are planning to do in the next 2 months. This will be > a major update to PHPDocumentor, as it will require adding in several new > classes, revamping the Data subpackage, and so on. We could definitely use > input on output formatting, as that is really the most important thing, > since it is the ultimate goal. > > Thanks, looking forward to opening the dialog, > > Gregory Beaver > Joshua Eichorn > http://phpdocu.sourceforge.net > > ----- Original Message ----- > From: "Jesus M. Castagnetto" <jcastagnetto@yahoo.com> > To: "Antonio Carlos Venancio Junior" <floripa@organiKa.com.br> > Cc: "Brent Cook" <busterb@mail.utexas.edu>; "PEAR" > <pear-dev@lists.php.net>; > "Tim Gallagher" <timg@sunflowerroad.com>; <jeichorn@phpdoc.org>; > <cellog@users.sourceforge.net>; <ulf.wendel@phpdoc.de> > Sent: Monday, April 29, 2002 3:55 AM > Subject: Re: [PEAR-DEV] PHPDoc renderer not working > > > > Antonio, > > > > --- Antonio Carlos Venancio Junior <floripa@organiKa.com.br> wrote: > > > Jesus, > > > > > > > > > Just for curiosity: I tried about 3 times to generate documentation for > > > 3 files and never get it to work. =) > > > > I've had no problem just getting the latest from CVS (pear/PHPDoc), making > the > > pear dir available from my local web server, and then just running it on, > for > > example, pear/Math_Science. > > > > > We are just trying to continue Ulf's work and release something stable > > > (yeah, it's beta yet). We have a lot of improvements to make. > > > > Parsing speed will be a good improvement. Perhaps also modify the system > to use > > the pear/PECL/phpdoc C extension, which seems to have 2 functions defined: > > confirm_phpdoc_compiled and phpdoc_xml_from_string > > > > Also, it will be good if PHPDoc detected previously created XML files, and > > asked the user whether to use them and just generate a rendering or to > process > > the classes again. In this way, an aborted rendering can be restarted. > > > > > And I didn't know about this other project, that seems a brother of > > > PHPDoc (maybe a clone). > > > Why don't merge both works and make an "Official" PHPDoc engine using > > > all our skills and time ? > > > What do you all think about that? =) > > > > As a user of PHPDoc/phpdocu(mentor), anything that makes things faster and > more > > reliable is good in my book. Go for it. > > > > > > > > On Sat, 2002-04-27 at 21:48, Jesus M. Castagnetto wrote: > > > > You might want to take a look at phpdocu.sourceforge.net > > > > > > > > In (informal) tests running PHPDoc (using the web interface, which > works OK > > > > btw), and phpdocu (command line interface). The second one was faster, > > > mainly > > > > because it did not generate intermediate XML files. > > > > > > > > When running PHPDoc on pear/Math_Vector (local version, with several > > > > modifications, like addition of unit tests and more examples), I had > to > > > stop > > > > the run after 2.5 hours (yes *hours*). In contrast phpdocu took 46 > seconds > > > to > > > > produce the documentation. > > > > > > > > The second documentation tool, has its quirks, but on the other hand > allows > > > > documentation to be associated w/ packages, functions, define(), etc. > And > > > seems > > > > to be OK w/ tags like: > > > > > > > > @see NameOfOtherClass > > > > > > > > which PHPDoc reports as incorrect, even though it is correct according > to > > > > JavaDoc specs. I like PHPDoc, it is more complete than phpdocu, but if > I > > > have > > > > to wait for hours vs seconds, then guess what will be the tool that I > will > > > use > > > > on a day to day basis. > > > -- > > > > > > > > > Cya > > > > > > > > > +++ > > > Antonio CVS .: organiKa :. > > > "We use only recicled bits" > > > floripa@organiKa.com.br > > > http://www.organiKa.com.br > > > Key fingerprint = 9F5B 31B0 C52A 4C4D 3A37 3A9F 7304 2779 5BBE B073 > > > > > > > > ATTACHMENT part 2 application/pgp-signature name=signature.asc > > > > > > > > ===== > > --- Jesus M. Castagnetto (jcastagnetto@yahoo.com) > > > > Research: > > http://metallo.scripps.edu/ > > Personal: http://www.castagnetto.org/ > > > > __________________________________________________ > > Do You Yahoo!? > > Yahoo! Health - your guide to health and wellness > > http://health.yahoo.com > > -- Cya +++ Antonio CVS .: organiKa :. "We use only recicled bits" floripa@organiKa.com.br http://www.organiKa.com.br Key fingerprint = 9F5B 31B0 C52A 4C4D 3A37 3A9F 7304 2779 5BBE B073

Attachment: [application/pgp-signature] This is a digitally signed message part signature.asc