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

On Wed, May 10, 2000 at 07:28:27PM +0200, Ulf Wendel wrote: > I'm quite surprised to see javadoc styled docs in PEAR. Just got the RC2 > and the PEAR Code reminds of my latest PHPLIB Contributions... Stig, are > you using certain rules for you inline documentation? Is this the > starting point of a documentation standard for PHP? I'm about to write a > kind of PHPdoc to extract my docs in the phplib cvs. And yes, I have > some scripts that extract the inline docs from the phplib cvs, although > they have alpha level. > > I like the idea of adopting javadoc very much. javadoc automatically > generates browseable docs by extracting comments from the source (those > who haven't seen it before, have a look at: > http://java.sun.com/j2se/1.3/docs/api/index.html). These docs > are great > for experienced programmers that simply need a reference. > > 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. Nowadays Hartmut Holzgraefe works at SIX, and he is able to fine tune the customizing of the stylesheets for a manual everybody can print. Hartmut have a database with all function_names and with all versions the functions are in. In this tables you can see which functions are documented in which language (en, de, it, jp). The basis of this work is in the folding hooks (I call them function prototypes). This function prototypes can be extracted with simple shell or AWK programs. The work what Hartmut made will be probably the basis of a index in the manual. Javadoc looks to me like to the suggestion to use LaTeX for a future manual. Javadoc is in my opinion a step back. -Egon -- Grueninger Str. 6, 70599 Stuttgart http://php.net/manual/, http://php.net/books.php3 http://www.uni-hohenheim.de/~windband http://snaps.php.net/manual/, http://www.zend.com/