Re: PHPod documentation

My 2 cents: I do not see the problem on putting descripitons and examples of usage in the javadoc-style that is phpdoc. Javadoc itself allows to put markup that indicates formatting if that is what you need, by allowing the use of HTML in the comment section of the documentation, see: http://java.sun.com/j2se/javadoc/writingdoccomments/index.html (in particular the example on documentation at the end of the page) WIth that in mind, I do not see the advantage of a POD style documentation system, unless someone has a more compelling reason than just a formatting capability. --- "Stig S. Bakken" <ssb@alltheweb.com> wrote: > 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 > > -- > PEAR Development Mailing List (http://pear.php.net/) > To unsubscribe, e-mail: pear-dev-unsubscribe@lists.php.net > For additional commands, e-mail: pear-dev-help@lists.php.net > To contact the list administrators, e-mail: php-list-admin@lists.php.net > ===== --- Jesus M. Castagnetto (jcastagnetto@yahoo.com) __________________________________________________ Do You Yahoo!? Make international calls for as low as $.04/minute with Yahoo! Messenger http://phonecard.yahoo.com/