Re: [PHP4BETA] Re: [PHP-PEAR] PEAR javadoc-style docs

eschmid+sic@s.netic.de wrote: > > On Wed, May 10, 2000 at 07:28:27PM +0200, Ulf Wendel wrote: > > Javadoc means placing some "tags" on certain places in the source. The > > tags are very simple and look like @param, @return, @access etc. The > > rules on writing javadoc comments are quite easy to understand. > > Extracting doc comments from the source can easily be done with some > > regular expressions. That's a great advantage compared to xml docs. You > > don't have to care on a PHP that has XML enabled and even more > > important: you don't need a DTD that defines the documentation rules. > > > > Let's talk about my way on documenting source. phpdoc comment start with > > /** and end with */. Same as with javadoc there're only recognized when > > placed in front of certain language keywords: class, function and var. > > Here's an example: > > Huh! Thats not the way the documentation is done. We use emacs folding > hooks. This is nearly complete in PHP3 and need some tweaking to the > module authors for PHP4. > > XML is IMHO the best way to document a language. There is now way to told > every module author to use javadoc. Javadoc is in my opinion a proprietary > format and doesn't fit into the XML scheme. > > It would be a very bad idea to rebuild the manual from scratch. We > started in 1997 with a SGML format and switched over to XML and this was > very wise decision. I'm not talking about the manual. No doubt SGML and XML is the choice when you're writing a manual for big class collections such as phplib or even php itself. But that's not my intention. I want some rules for writing inline documentation, that can be used to generate a quick references that help experienced programmers working with new classes/modules. Just take the class you've found somewhere, run "phpdoc" and get a brief overview. I'm afraid that as soon as PEAR gets well documented an PHP4 is released everybody who has ever placed a script in an archive will to convert it to the PEAR standard and place it in the PEAR tree. Most of these classes won't have any documentation. If the PEAR coding standard says that inline documentation is a must, you'll be at least able to get a reference out of the source. The best way of inline documentation to generate references is javadoc. I prefer it over XML. If we would use XML we would have to develop a DTD. If we use six, seven or maybe eight @something-"tags" we have some very few, simple rules. These tags are very familiar to those who know java and those who do not, will not have difficulties learning them. By the way, if you start working with XML people will not stop asking for new features... Ulf