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.

Inline tags

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


  This article uses material from the Wikipedia page available here. It is released under the Creative Commons Attribution-Share-Alike License 3.0.

PHP_Programming/phpDocumentor
 



 

Connect with defaultLogic
What We've Done
Led Digital Marketing Efforts of Top 500 e-Retailers.
Worked with Top Brands at Leading Agencies.
Successfully Managed Over $50 million in Digital Ad Spend.
Developed Strategies and Processes that Enabled Brands to Grow During an Economic Downturn.
Taught Advanced Internet Marketing Strategies at the graduate level.


Manage research, learning and skills at defaultLogic. Create an account using LinkedIn or facebook to manage and organize your Digital Marketing and Technology knowledge. defaultLogic works like a shopping cart for information -- helping you to save, discuss and share.


  Contact Us