PHP CookBook

Recipe 21.9 Documenting Classes with PHPDoc

21.9.1 Problem

You want to be able to integrate documentation with your code.

21.9.2 Solution

Use PHPDoc. This allows PEAR to accurately list your class, and you can use the PHPDoc tools to automatically generate API documentation in HTML and XML.

PHPDoc syntax is based on Javadoc. The following tags are available for use: @access , @author, @package, @param, @return, @since, @var, and @version.

You can then use PEAR's PHPDoc utility to generate documentation.

21.9.3 Discussion

PHPDoc has a special inline documentation style. By formatting your comments in a particular way, the PHPDoc script can parse your code to not only generate which parameters a function take and what type of variable it returns, but also associate comments and other useful information with objects, functions, and variables.

PHPDoc comments are based on the same formatting and naming conventions as Javadoc. So, to flag a comment block to grab PHPDoc's attention, use a traditional C-style comment but use two asterisks after the opening slash:

/**
* This is a PHPDoc comment block
*/

Inside of a block, certain keywords have special meaning. These keywords all begin with an at sign. Table 21-2 lists the keywords and what they stand for.

Table 21-2. PHPDoc keywords

Keyword	Meaning
@access	Method access: public or private
@author	Package author
@package	Package name
@param	Function parameter
@return	Function return value
@see	See also reference
@since	Debut version of PHP
@var	Object variable
@version	Package release number

A more fully fleshed out example looks like this:

/**
* Example_Class is a sample class for demonstrating PHPDoc
*
* Example_Class is a class that has no real actual code, but merely
* exists to help provide people with an understanding as to how the
* various PHPDoc tags are used.
*
* Example usage:
* if (Example_Class::example()) {
*    print "I am an example.";
* }
*
* @package  Example
* @author   David Sklar <david@example.com>
* @author   Adam Trachtenberg <adam@example.com>
* @version  $Revision: 1.4 $
* @access   public
* @see      http://www.example.com/pear
*/
class Example extends PEAR
{
    /**
    * returns the sample data
    *
    * @param  string  $sample the sample data
    * @return array   all of the exciting sample options
    * @access private
    */
    function _sampleMe($sample)
    {

Any text following a keyword is treated as the value assigned to it. So, in this example, the value of @package is "Example." It can be okay to have two instances of the same keyword, depending upon the situation. For instance, it's perfectly legal to have multiple @param keywords, but it's illegal to have multiple @return keywords.

PHPDoc and the PEAR web site use this information to generate hyperlinked references, so it's important to use a consistent naming scheme, or the cross-references won't work correctly.

To generate PHPDoc, first install the PHPDoc PEAR package. Inside that package is a program named phpdoc; run it from the command line, and use the -s flag to pass in the directory of the source files. By default, documentation is generated in /usr/local/doc/pear/, so be sure the phpdoc program has write permission to that location, or use -d to alter the destination directory.

To permanently modify the default values, edit the values at the top of the script. Pass -h for a listing of all possible command-line parameters.

PHPDoc isn't very efficient, so be patient. Generating documentation may take a while, depending upon the size of your files. A faster program is currently under development.

21.9.4 See Also

PEAR coding standards at http://pear.php.net/manual/en/standards.php; PHPDoc at http://pear.php.net/package-info.php?package=PHPDoc.