RE: [PEAR-DEV] PHPod documentation

> 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. > My original thinking, based on a perl presentation at OsCon, was a pod to docbook converter. Basically you document inline with pod and the filter converted it to docbook for you along with a zillion other formats as well as easy integration with the existing php documentation. Having inline documentation IMHO means that while the code is 'uglier' all documentation and code is self-contained. If you've ever had to poke around in perl modules, you'll know how handy self-contained documentation is. Plus a developer is more likely to update inline docs than to update seperate docs when modifying a class. Anyway, it's kinda academic now because we're going to take a closer look at PHPDoc now although I'm glad my suggestion has stimulated plenty of discussion. Time to look at Javadoc :) Cheers, Graeme