PHP Programming/phpDocumenter
From Wikibooks, the open-content textbooks collection
Contents |
[edit] Guide to phpDocumenter
phpDocumenter is a tool for automatically generating easily readable documentation for a piece of software using inline comments.
[edit] Why use phpDocumenter?
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 phpDocumenter, you can achieve both. When writing the documentation, you simply insert special comments in your code. phpDocumenter will then parse your code an generate easy-to-use documentation in HTML, DocBook, or PDF.
[edit] Basic Usage
The comments which are picked up by phpDocumenter 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, phpDocumenter 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 phpDocumenter.
[edit] Format of a phpDocumenter comment
There are three sections to a phpDocumenter 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
{
...
[edit] 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 phpDocumenter.
