Re: javadoc, phpdoc, XML, and PEAR

Quoting eschmid+sic@s.netic.de: > The current system to write folding hooks into the PHP source is very > simple. But almost all coders haven't seen the result of this effort and > can or will not follow the CODING_STANDARDS. Okay. Correct me if I'm wrong, but isn't this system - and CODING_STANDARDS - meant to apply to the php source code - ie, code written in c? If so, then people writing code in php - like PEAR modules - aren't even expected to look at CODING_STANDARDS... > I don't see any need that PEAR modules must have the same inline docs like > the PHP source code. Useful information could be extracted from every sort > of inline docs. Right! I think that a modification of javadoc is a good _inline_ system for PEAR; it could probably even be used to generate a useful starting point for external documentation, like I suggested before. > The same here. But don't touch the existing inline docs. In PHP 4 there > should be more. For the comprehensive docs, this mean, we can place that > information directly into the manual so users can make an annotation if > there is something missing. I (and I don't think Ulf) ever suggested changing the existing inline php docs. We're just talking about inline documentation in PEAR modules - an entirely different beast, as far as I'm concerned. > Look at Hartmuts work at > http://www.zugeschaut-und-mitgebaut.de/php/ and > you should know what I mean. A manually sorted list of the folding hooks > (or protos) can be found in Rasmus Pocket Reference. Yes - it's very useful. But a system like that takes a talented and dedicated documentation team - correct me if I'm wrong, but I don't think you guys want to take on maintaining documentation for every PEAR module, do you? So PEAR should use a method of inline documentation that encourages individual authors to document their work, in such a way that generates generally useful output. -chuck