Re: PHPod documentation

"Tomas V.V.Cox" wrote: > > "Stig S. Bakken" wrote: > > > > "Stig S. Bakken" wrote: > > > > > > Chuck Hagenbuch wrote: > > > > > > > > Quoting Jon Parise <jon@php.net>: > > > > > > > > > I'm sort of leaning toward developing our own PearDoc system that > > > > > is based on the existing PHPDoc / JavaDoc syntax (because of > > > > > legacy code and familiarity), but I would really like to see the > > > > > capabilities of POD-style documentation be added, too. > > > > > > > > For those of us who've never used POD, maybe if someone were to explain > > > > what > > > > those (the capabilities of POD-style documentation) are, it would help? > > > > > > POD stands for "Plain Old Documentation" and is an embedded > > > documentation format used by Perl. For examples, look at any .pm file > > > in /usr/lib/perl5/site_perl. POD is very plain text-centric, but that > > > doesn't mean we can steal the ideas and use them in a different way. > > ^^^ > > can't > > It could very great to standarize the documentation of pear classes (not > mean the API), and adopting a "low-weight" system like POD could be one > approach. Personally I find that having all the documentation inside the > source code is ugly and make things harder to maintain. My vote is to > have the class doc outside in a separate directory, also standarize dir > names. For ex: > > Money_Fast (*) > | > +-docs > | > +-api > +-examples > > I'm sure this will benefit the pack/install process. The <File> package.xml element can already label files as documentation in a certain format, so IMHO such a structure should be encouraged, but not "enforced". > Thinking about POD ... if docbook was one of the most successful things > of PHP, why change it? We're not changing anything, something POD-inspired could augment the PHPDoc format, which is already not using DocBook for good reasons. For external documentation, people should use whatever they like as long as it can be (or converted to something that can be) viewed in any browser. IMHO people whom DocBook appears to as an unsurpassable wall of tags should be able to use HTML or even just plain text. > I know it is more difficult than the simple POD, > but this could be solved providing a basic xml template, basic examples, > basic tools or even a POD to Docbook converter. We should also need to > hear the opinion of the doc team folks. Any way, If you are sure that > having POD will make people to start writing tons of doc, go ahead :) > Other thing is to adopt some POD tags to the actual Javadoc system, I > guess that nobody has problems here. > > Tomas V.V.Cox > > (*) Money Fast is a trademark of Stig S. Bakken Check my From: address.. ;-) - Stig