Re: PHPod documentation

Graeme Merrall wrote: > > > 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? > > I wasn't suggesting we replace phpdoc/javadoc, although that could be an > idea I guess. My thinking was rather than documenting functions/classes a la > javadoc style, the pod documentation would actuially serve as documenting > the module itself. e.g. usage examples, general documentation, gotchas etc. > Take for example Thomas' DB docs. A cut down example could be added to DB to > make the module self documenting. Besides, pod is better suted to longer > stretches of text AFAIK not little snippets for functions like javadoc. > > I think javadoc is still good though as it is more suitable for documenting > parameters and return values for functions and I can't see why they can't > sit side by side as they serve two essentially different purposes. > pod = PEAR user > javadoc = PEAR developer But these two systems have slightly different markup syntaxes, JavaDoc has metadata markup, while POD has formatting markup. What about combining the two into PHPod: we could easily document function parameters etc. with a POD-like format too, and and a bonus we would not inherit all the features from JavaDoc that don't really fit too well with PHP, but we can define a format that is perfect for PHP. What about this: /*= =param $arg mixed description of $arg =param [$opt] bool description of optional boolean arg =head1 Description This function does bla bla bla... =item bla =item bla bla =item bla bla bla */ or keeping the JavaDoc syntax: /** * @param $arg mixed description of $arg * * @param [$opt] bool description of optional boolean arg * * @head1 Description * * This function does bla bla bla... * @item bla * @item bla bla * @item bla bla bla * * @see Other_Class */ I just don't see the point in mixing them. - Stig