Section B.5. Using the phpDocumentor Tool

B.5. Using the phpDocumentor Tool

You need the phpDocumentor tool to generate the documentation from the sources enhanced with the tags from the previous section. This tool is installed along with some templates when you type pear install phpDocumentor. The tool has several parameters that are listed in Table B.2. phpdoc -h gives you a full overview of parameters; here the most important are described:

Table B.2. phpDocumentor Tool Parameters

Option	Comments	Example
-f, --filename	Comma-separated list of files to parse. You can use the wildcards * and ?.	-f index.php,index2.php
-d, --directory	Comma-separated list of directories to parse, with the same wildcards supported as with -f.	-d lib*,core
-ed, --examplesdir	Full path to the directory with examples.	-ed /local/examples/sumexample
-t, --target	Target directory for the generated documentation.	-t /local/docs/sumexample
-i, --ignore	Files that will be ignored during parsing, just as -f and -d are the wildcards that * and ? supported.	-i internal.php
-ti, --title	Title of the generated documentation.	-ti "Sum Example"
-pp, --parseprivate	With this option on, @internal and elements with @access private will also be put in the generated documentation.	-pp on
-o, --output	The output, converter, and template to use for generated documentation.	-o HTML:frames:default
-s, --sourcecode	If this option is on, generated documentation will also include syntax-highlighted source code.	-s on

To start generating documentation with phpdoc, use the following command:

 $ phpdoc -d directory -pp on -s on -o HTML:frames:default -t outputdir 

Tip:

All warnings and errors are placed in the file errors.html when you're running in HTML mode.

See the following example of how the generated documentation would appear. From this PHP source file, we will generate documentation with the default template:

 <?php /** * Example included file with utility functions * @author Derick Rethans <[e-mail]> * @version $Id: $ * @package PHPDocExample * @subpackage PHPDocExampleFunctions */ /** * Function to add numbers in arrays * * This function returns an array in which every element is the sum of the * two corresponding  elements in the input arrays. * @since Version 0.9 * @param array $array1  The first input array * @param array $array2   The second input array * @return array */ function sumElements ($array1, $array2) {     $ret = $array1;     foreach ($array2 as $key => $element) {         if (isset ($ret[$key])) {             $ret[$key] += $element;         } else {             $ret[$key] = $element;         }     }     return $ret; } ?> 

The file with error class is

 <?php /** * @author Derick Rethans <[e-mail]> * @package PHPDocExample * @subpackage PHPDocExampleFunctions */ /** * File with utility functions */ require_once 'utility.php'; /** * The error class * This error class is thrown when an error in one of the * other Sum* classes occurs * @author Derick Rethans <[e-mail]> * @author Stig Bakken <[e-mail]> * @copyright © 2002 by Derick Rethans * @version $Id: $ * @package PHPDocExample */ class SumError {     /**     * The constructor for the error class     * @param string $msg Error message     */     function SumError ($msg)     {         echo $msg. "\n";     } } ?> 

The file with the Sum class is

 <?php /** * This class adds things * This class adds things * @author Derick Rethans <[e-mail]> * @copyright © 2002 by Derick Rethans * @package PHPDocExample */ /** * @author Derick Rethans <[e-mail]> * @copyright © 2002 by Derick Rethans * @version $Id: $ * @package PHPDocExample * @since version 0.3 * @abstract */ class Sum {     /**     * @var string $type Type of the elements     */     var $type;     /**     * @var mixed $result Result of the summation     */     var $result;     /**     * Constructor     * @param string $type  The type of the elements     */     function Sum ($type)     {         $this->type = $type;     }     /**     * Sum elements     *     * Sums elements     * @abstract     * @param mixed $elem1  The first element     * @param mixed $elem2  The second element     */     function sumElements ($elem1, $elem2)     {         return new SumError('Please overload this class');     }     /**     * Return the result of the summation     * @abstract     * @return mixed     */     function getResult ()     {         return $this->result;     } } ?> 

The file with the SumNumberElements class is

 <?php /** * @author Derick Rethans <[e-mail]> * @package PHPDocExample */ /** * Class for adding arrays of numbers * Class for adding arrays of numbers * @author Derick Rethans <[e-mail]> * @copyright © 2002 by Derick Rethans * @version $Id: $ * @package PHPDocExample * @final */ class SumNumberElements extends Sum {     /**     * Function which sets the result for the Summation     * Function which sets the result for the Summation     * @param mixed $elem1  The first element     * @param mixed $elem2  The second element     * @access public     */     function sumElements ($elem1, $elem2)     {         /* Uses the sumElements utility function */         $this->result = sumElements ($elem1, $elem2);     } } ?> 

The file with the SumNumbers class is

 <?php /** * @author Derick Rethans <[e-mail]> * @package PHPDocExample */ /** * Class for adding two numbers * @author Derick Rethans <[e-mail]> * @copyright © 2002 by Derick Rethans * @version $Id: $ * @package PHPDocExample * @final */ class SumNumbers extends Sum {     /**     * Functon to add numbers     *     * This functions adds numbers     * @see sumElements()     * @access private     * @param integer $int1  The first number     * @param integer $int2  The second number     * @return integer     */     function _sumNumbers ($int1, $int2)     {         return $int1 + $int2;     }     /**     * Overloaded SumElements function     *     * Overloaded SumElements function     * @access public     * @param int $elem1  The first element     * @param int $elem2  The second element     */     function sumElements ($elem1, $elem2)     {         $this->result = _sumNumbers ($elem1, $elem2);     } } ?> 

Now that we have the source files, we generate the documentation with

 $ phpdoc -d sums -pp on -s on -t Example -o HTML:frames:default -t sums_generated 

Tip

There are plenty of other templates that you can usefor example, HTML:frames:earthli for colorful documentation with images indicating different elements, PDF:default:default for a PDF documentation of your classes, or HTML:Smarty:PHP for a layout similar to the php.net web site layout. See the /usr/local/lib/php/PhpDocumentor/phpDocumentor directory and subdirectories for more supported templates. (You might have to check a different path, depending on your PEAR installation.)

Some screenshots from the generated documentation follow (see Figure B.2 and Figure B.3).

Figure B.2. SumNumber elements documenation.

Figure B.3. Method overview.

These screenshots (Figures B.2 and B.3) show the documentation of the SumNumberElements class. The left pane shows the classes and modules in this package and the right pane shows all information of the SumNumberElements class. You can clearly see that this class is inherited from the Sum class in the class tree at the top. The second screenshot shows detailed information about the one method in this class sumElements and the methods that are inherited from the Sum class (such as the Sum::Sum() and Sum::getResult() methods).

Figure B.4 shows the relation between all classes in the package as a tree. It shows that the SumNumbers and SumNumberElements classes are sub-classes of Sum, and that the SumError class has no super- or subclasses.

Figure B.4. Relations between packages.

Another interesting screenshot (see Figure B.5) shows an index of all available elements in the packages. Shown elements are modules, classes, functions, variables, and constants. Have a look at fully generated documentation from our example scripts, which you can find online at the book's web site.

Figure B.5. Overview of all elements in the package.