Re: javadoc, phpdoc, XML, and PEAR

Joey wrote: > > 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 There is really no "conflict" between the current way in PHP of marking up prototypes, and XML documentation. From the inlined function prototype you can generate a RefNameDiv element in the XML, and in the following one-liner you have the contents of the RefPurpose element. > 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> I don't mean to be Mr. Party-pooper, but having entire PEAR files conform to a DTD means that PHP has to be an XML parser, which would slow down the parsing considerably. Any feature slowing down parsing needs to justify its existence, and I don't think making inline documentation in a certain way justifies it. The idea you toss in about looking for deprecated functions is cool. The functionality you are suggesting (not only checking for specific functions, but tracing the output as well) is called static code analysis. I'm not a compiler guru, but I have a feeling writing one is about the same amount of work as writing an optimizing parser/compiler. :-) Catching unquoted strings and so on could be done in a "PHP lint" program. It would make sense to extend the parser (Zend) with a mode for this. Take a look at the file "dblib.dsl" in the DSSSL stylesheets we use for the PHP Manual, it has comments with some sort of markup before functions, and a tool called "dsl2man" apparently converts this to DocBook format.. > 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... Since this involves all of PHP, not only PEAR, php-dev is probably the right place for this discussion. - Stig