javadoc, phpdoc, XML, and PEAR

I have been carrying on a side conversation with Ulf Wendle (sorry if I hammered the spelling...) regarding the inline documentation for PEAR, and just thought I'd toss it out here for input: Ulf is working on a javadoc-like system for inline code documentation, and would like it to be considered for use in PEAR. Both Egon and I mentioned that: A) There is already a system in PHP for inline docs B) This would not be compatible with XML versions of documentation Here is the most recent piece of our conversation (part of Ulf's meesage is in comments): <begin quote> > hmmh - that makes sense. How about a compromise. For the moment we'll > use phpdoc to generate references and API documentations. Later on we'll > translate the phpdoc tags into XML and work on DTD for PEAR manuals. > This work has to be done together with the php documentation team, > escpecially Egon and Hartmut. I agree. All of the above sounds great! I know that java/phpdoc is simpler to learn/use, but one of my biggest frustations with Open Source products is the poor documentation, and I really think that when PEAR is big enough, that XML will come in really handy. What would be, IMHO, ideal, is that a whole given PEAR file has to conform to a DTD, which will: * Make sure code is commented, and properly * Catch typos, missed }'s, hanging if statements, etc. * Possibly enforce CODING_STANDARDS, and give people hints on what they might be doing wrong/oddly. * Watch for deprecated usage. Things like using "if" on mysql_pconnect, which no longer returns an int, but instead returns a resource handler. * Catch $a[some_string} and convert-on-the-fly to $a["some_string"], where appropriate. This are just of the few things that I can think being an advantage to XML, and if the proto system is used (as described in CODING_STANDARDS), then we can still use the old awk scripts to do extraction. These scripts have been written, tested, and used quite a bit...(though I never could get them to work on Sun's awk ;) I guess I am partial, as a friend and I are tossing around the idea of a PHP/HTML/JavaScript IDE, and we would love to be able to use the XML DTD to validate results from our IDE. In fact, we have even done about 15 mins worth of work on what we thought the IDE and validating parser would look like, prototyped in C++ Builder. :) </end quote> Is this the right place for this traffic? Obviously, there are a lot of ideas being thrown around...what is the proper forum? The php-doc list? Your average parser and DTD will not be robust enough to do all the things I would like it to do, allowing the implementation of the above features, and anything else we can think of...my partner is the real XML guru of us, but he has some ideas if anyone is interested... --Joey Smith Please forgive the long sig: *** Notice To Bulk Emailers: Attention! Pursuant to US Code, Title 47, Chapter 5, Subchapter II, 227, any & all unsolicited commercial e-mail sent to this address is subject to a download and archival fee in the amount of the $1500 US and copies will be forwarded to domain administrators. Emailing denotes acceptance of said terms!