Hack 85. Generate Documentation Automatically
 
Use PHPDoc comments to document your code, and use the phpDocumentor to build your documentation from code comments.
JavaDoc is the commenting standard for Java, and it is used to generate documentation for Java classes automatically. This comment-to-documentation idea was so popular that now almost every language has a comment markup that can be used to automatically generate documentation.
For PHP, there's PHPDoc; it makes writing programmers' documentation for your classes much easier for everyone involved. phpDocumentor (http://www.phpdoc.org/) is an open source tool that parses PHP code, extracts the PHPDoc documentation, and generates HTML from the source, all with a variety of different styles. Figure 8-7 illustrates how PHPDoc takes PHP files as inputin this case, Author.phpand creates a set of HTML files as a documentation package.
8.8.1. The Code
Save the code in Example 8-17 as Author.php.
Example 8-17. The PHPDoc marked-up Author class
<?php
/**
* An author class
*/
class Author
{
/**
* Gets the name of the author
*/
function getName() { }
/**
* Sets the name of the author
* @param string $name The name of the author
*/
function setName($name) { }
}
?>
8.8.2. Running the Hack
In this case, running the code means running the phpDocumentor command on the PHP files in your project. The Author.php file is an example of a class marked up with PHPDoc comments, which all begin with the distinctive /** syntax and end with */. The text in these special comments then becomes part of the PHPDoc documentation.
The @param markup element tells the documentation generator that what follows is the type of parameter, followed by the name of the parameter, followed then by a description of the parameter. For a complete list of these markup elements, you should reference the phpDocumentor documentation (http://www.phpdoc.org/). I'll list a few of the more important ones here:
@author -
Specifies the author of the code.
@copyright -
The copyright specification for the code.
@license -
The license text of the code.
@see -
Cross-links between this class or method and another class or method. The text that follows this tag is the textual identifier of the class or method being referenced.
@param -
Documents a function parameter.
@return -
Documents the return value of the function.
@todo -
Information on what is left to do for this piece of code.
You run the phpDocumentor command this way:
phpdoc -t doc -f *.php
 |
The HTML output will be generated in the doc directory.
|
|
Run the command, and you will see a lot of output as the documentation is generated. Double-click on the docs/index.html page in your browser and you will see something that looks like Figure 8-8.
Using the navigation panel on the lefthand side of the window, click on the Author class link and you will find everything you need to know about the Author classor at least as much as the programmer commented onas shown in Figure 8-9.
I've used just a few of the basic PHPDoc comment constructs in the Author.php class file. Many more PHPDoc documentation keywords allow for cross-linking documentation, hyperlinks, and more.
8.8.3. See Also
| 