21.9.1. Problem

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.

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

21.9.3. Discussion

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

Table 21-2. PHPDoc keywords

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.3 $
* @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.