Re: PHPod documentation

"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. Thinking about POD ... if docbook was one of the most successful things of PHP, why change it? 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