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

Ulf Wendel wrote: > > 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. > What about POD. Its easy, well known, and proven to work (CPAN)? Sterling