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

Apple has released OpenSourced tool they call HeaderDoc (http://www.publicsource.apple.com/projects/headerdoc/) which generates JavaDoc style HTML from C/C++ files. I have tried it and it works pretty well with PHP code right out of the box. It is written in Perl and and creates so pretty nice HTML. Michael Ulf Wendel wrote: > Hi! > > 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: > > /** > * New OOH Forms. Generate and validate HTML Forms. > * @version 1.1 > * @author Ulf Wendel, ulf@redsys.de > */ > class form { > > /** > * Show error messages and warnings? > * @var boolean $flag_show_error = false true means show > * @access private > * @see flag_halt_on_error, showError(), getError(), setError() > */ > var $flag_show_error = false; > > /** > * Print an error message. To show error messages > * you have to set flag_show_error = true > * @access private > * @see > function showError() { > } // end func showError() > > } // end class form > > When I started I noticed that some javadoc tags don't need any changes, > some others need modifications and some new have to be introduced. In > the end I ended with very few essential tags. Here're my rules. > > "dspace" stands for [ \t\n\t]+, [\t] is the preferred seperator. A tag > ends at the next "@" or "*/". Don't look at the regexp syntax - > you'll > understand it anyway. > > +++ allowed variable types +++ > > - enum(value1, [value2]) > - string > - int > - double > - float > - boolean > - object [name of object] > > The variable type must be specified when using: @param, @var, @return. > It alway stands in front of the variable name. That makes reading > easier. > > +++ @version +++ > > @version [dspace] something > allowed in front of: class, function > > Version of class or a function. > > +++ @author +++ > > @author [dspace] name, email > @author [dspace] name, email [; name, email] > allowed in front of: class, function > > Name -and- email of the author(s). > > +++ @var ++++ > > @var [dpspace] var_type [dpspace] $var_name[=["']somevalue["']] > [dspace] notes and explanations > allowed in front of: var (within a class) > > +++ @param +++ > > @param [dspace] var_type [dspace] $var_name[=["']somevalue["']] [dspace] > notes and explanations > allowed in front of: function > > If you have function, that can handles different variables types, you > have to write a @param line for every variable type allowed: > > /** > * [...] > * @param string $elname name of an element > * @param array list of elements ( $k => $name ) > * [...] > */ > function getValues($elname) { > if (!is_array($elname)) > $elname = array($elname); > > reset($elname); > while (list($k, $name)=each($elname)) > ... > > I have no idea how to write comments for "vararg" functions. Suggestions > are welcome! > > +++ @return +++ > > @return [dspace] var_type [dspace] > $suggested_var_name[=["']somevalue["']] > allowed in front of: function > > +++ @access +++ > > @access [dspace] [public|private]{1} [dpspace] notes and explanations > allowed in front of: var, class, function > > I know that PHP does not distinguish between public and private > functions. Nevertheless this is an intresting information. Am I allowed > to access an class/instance var to improve speed or do I have to use an > accessor function? > > +++ @see +++ > > @see [dspace] var [, method()] > allowed in front of: var, class, function > > Use "var_name" (no $) to define a link to a class/instance variable and > "method()" ("()" as an indicator) to define a link to a function/method. > > Quite simple, isn't it? Just seven simple tags, that help building a > reference for a (PEAR) class (module). Is anyone intrested in writing a > PHPDoc? Please anwser by PM. > > Ulf > > -- > PHP 4.0 Beta Mailing List <http://www.php.net/version4/> > To unsubscribe, e-mail: php4beta-unsubscribe@lists.php.net > For additional commands, e-mail: php4beta-help@lists.php.net > To contact the list administrators, e-mail: php4beta-admin@lists.php.net