PHP Programming/phpDocumentor
phpDocumentor is a tool for automatically generating easily readable documentation for a piece of software using inline comments.
Why use phpDocumentor? edit
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 edit
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
{
...
Format of a phpDocumentor comment edit
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 edit
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.
Inline tags edit
Elements Documented By phpDocumentor edit
Generating Documentation edit
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 edit
- 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.