PHP Programming/phpDocumentor

phpDocumentor is a tool for automatically generating easily readable documentation for a piece of software using inline comments.

Why use phpDocumentor?

The ideal documentation has two properties. First, it should be easy to maintain and keep up to date. Secondly, it should be easy for the reader to read and navigate the document. These are often contradictory goals. By using tools just as javadoc and phpDocumentor, you can achieve both. When writing the documentation, you simply insert special comments in your code. phpDocumentor will then parse your code an generate easy-to-use documentation in HTML, DocBook, or PDF.

Basic Usage

The comments which are picked up by phpDocumentor are C-style comments with two asterisks in the opening tag.

/**
 *
 */

These are known as DocBlock comments. By placing this before an element in your code, phpDocumentor will generate documentation for that element. For example, if I want to document the "RhesusMacaque" class, I would place a DocBlock immediatley before it.

/**
 * This documents the Rhesus Macaque
 */
class RhesusMacaque
{
...

See elements documented by phpDocumentor.

Format of a phpDocumentor comment

There are three sections to a phpDocumentor DocBlock. The first is a short summary of the code element, which should be no more than a sentence. Next is a few sentences describing the element in more detail, which are optional. Finally, there is a sequence of tags.

/**
 * The Rhesus Macaques rule the world through a secret conspiracy
 *
 * The Rhesus Macaques have been quietly watching human civilization
 * for centuries.  They have quietly influenced events through a
 * variety of mechanisms.  See class members for more details.
 *
 */
 class RhesusMacaque
 {
 ...

Tags

Tags can be inserted into DocBlocks to describe certain parts of a code element in more detail. They provide data such as the return type of a function, or the author of a piece of code. They are marked by an '@' symbol, and take the form

* @tagname properties

Each element type has a different set of tags which describe it. See elements documented by phpDocumentor.

Generating Documentation

A command such as

phpdoc --target /var/www/phpdoc --output "HTML:Smarty:php" --directory /var/www/app --filename **/*.php

will generate documentation from the PHP files found in /var/www/app.

For a complete list of output formats, see the PhpDocumentor website.

Note that the value of the output parameter is case-sensitive.

Errors

Converter HTMLsmartyConverter specified by --output command-line option is not a class

The 's' in 'smarty' should be uppercase.

template directory "/var/www/pear/PhpDocumentor/phpDocumentor/Converters/HTML/Smarty/templates/php/" does not exist

The 'php' should be uppercase.

External Links

• phpDocumentor homepage
• phpDOC homepage