Re: alternative to phpdoc....

This is surprisingly readable documentation! I like the idea of including the source right in there. It's almost like an extra insight into things, since they're both presented at once, source highlighted, and the docs are clear (not plain text like in source files). Very nice. Lux On Tue, 2002-05-07 at 12:42, Alan Knowles wrote: > I just spent the last few days playing with the tokenizer module (and > finding bugs in it:) - anyway below is a link of some of the results > > http://docs.akbkhome.com/pear/ > > illustrates pear documentation, > > and > > http://docs.akbkhome.com/phpmole/ > > illustrates phpmoles (lack of documentation :) > > ---------- > > anyway, it's an interesting little experiment.. - while doing it a > number of things became clear about the current phpdoc documentation - > which are really just a point of view, which this attempts to address. > > Adding the source luke... > phpdoc from what I have read is based on javadoc. - it seems clear that > the reason for documenting in this way is to generating documentation > that could be distrubuted without the source code., while this is very > common in java an c++ enviroments. the open source/php world is more > used to reading source.. - hence making the source available in the > documentation seemed quite sensible....... > > Ruby Class pages..... > The whole little adventure got started after I saw the ruby 'quick > reference pages' after a slashdot posting a while back.. - it seemed > alot clearer to view the whole framework/libraries summarized on one page.. > > Simplicity.... > The core class basically builds a big array of stdclass's containing > class/method/var information, based on the parse results. > There are 2 methods that then use a derivite of wolfram's template class > to build html pages (although you could do docbook or whatever with very > few changes..) - these templates where designed to be edited in mozilla > (handles urlencoded template tag issues) > > Short comment tags. > Most projects do not require such detailed documentation, so the ability > to read short comments following declarations.. > If I had more hours in the day, I would love to add phpdoc notes to all > my code, but short notes suit my needs most of the time... > > var $fred; //freds var stores xxxxxx > function some_internal($ssS) { // an internal funciton used to do stuff.. > > Anyway, all the code is phpmoles cvs, > tools/doc_phpmole.php - sample generator > tools/php_generator.class- the core bit > tools/Template/* - a modification of wolfram's template class > tools/*.html - all the html templates > (there is also an old effort at creating dia uml diagrams in there, but > that proved rather pointless in the end..) > > Theres more comming, but I'd be interested on hearing other ideas... > > regards > alan > > > > > > > > > > > -- > PEAR Development Mailing List (http://pear.php.net/) > To unsubscribe, visit: http://www.php.net/unsub.php > > >