Re: PHPod documentation

Graeme Merrall wrote: > > Arent' we all just super inspired after OsCon - especially Jon :) > > Jon may recall I asked him at the 'Future of PHP' session about Pod-like > documentation for PEAR. Since I thought it up I decided to do something > about it - vis PHPod for want of a better name. > Basically it's Pod-like system for PHP. Obviously since Perl handles POD > directly we cannot hope to fully emulate it. > > Couple of points: > 1. Wrapping the PHPod format inside /* */ should suffice. As long as > =directive is at the beginning of a line and docs end with =cut like Perl it > should be fine > > 2. Opportunity to extend the format. Adding extra tags such as =test would > be interesting for test code. This has already been noted as one limitation > of the Perl Pod system. > I was inspired by a paper at OsCon called DocPod which was an extensions to > the Pod system that enables docbook output including tables, lists and the > opportunity for an additional =code block to be parsed and the output sent > to the docbook <computeroutput> tags. Cool huh? This would allow intgration > of documentation of PEAR modules into PHPDOC without module authors having > to keep abreast of both. > > I've started to basically a 1-to-1 port of Pod::Html to PHP and it was > generating indexes and =head[1-6] tags nicely but I've bumped into a slight > hitch with tidying up the input POD data and some regexes. Will post more > details when I get a result and I've looked at DocPOD some more as well as > Pod::POM > > Thoughts? DocPod sounds like a very good idea. I think we should try still going through DocBook since it has been a success recipe for the PHP Manual for years. The idea behind POD is very appealing, I think it's better than Javadoc because of its no-nonsense approach. Also, with our current use of Javadoc it's not clear what markup is allowed, but this is actually defined in POD. How does everyone feel about maybe replacing Javadoc with something like "DocPHPOD" for PEAR? - Stig