Re: javadoc, phpdoc, XML, and PEAR

Quoting Joey <joey@samaritan.com>: > A) There is already a system in PHP for inline docs > B) This would not be compatible with XML versions of documentation I really think that people are still speaking crosswise somewhat. We're not talking about documenting c source - php modules. We're talking about documenting php code - PEAR modules, and hopefully a wider standard. I'd hope that this standard will be as simple as possible, because the main reason that open source projects have poor documentation is that IT IS A PAIN IN THE ASS TO WRITE! If you make every single person who wants to write a pear module learn xml to document their code, you're going to get a lot less code contributed to PEAR. The alternative is to have a team which will volunteer to document everyone's modules, but that seems extremely limiting (in volume), and not a good idea, since you want the person who wrote the code documenting it if possible. I like javadoc because it is: established with a large number of programmers, simple, and still expressive enough to be more useful than a one-line summary. I don't argue that XML is the way to go for comprehensive documentation - like the php manual - but the package indexes that javadoc generates I find extremely useful. We could even have phpdoc generate an XML skeleton for a package to aid in writing comprehensive documentation along with the phpdoc summary. THAT would be a great way to encourage people to write documentation, not make it too complicated for them, and aid the process of getting more comprehensive docs, all at the same time. -chuck