Re: PEAR javadoc-style docs

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