http://www.developer.com/

Back to article

Documenting PHP Code with PHPDocumentor


November 24, 2004

It's no secret; writing code documentation ranks right up there with attending meetings and the using the telephone as among the least favorite aspects of any developer's job. This shouldn't really come as a surprise though, since not only is writing documentation a pretty unexciting task, but it can be difficult to maintain over the lifetime of a project given changing features and code refactoring. Nonetheless, it's a crucial task if you and your team intend to create code that is maintainable well into the future, stretching even beyond your own role with the project ends.

To alleviate some of the tedium and potential for incorrectness, automated documentation tools were created. These tools parse comments and code declarations found in project source files, producing organized documentation in a user-friendly format. Some examples of such tools include POD for Perl, JavaDoc for Java, and Pydoc for Python. These tools are extremely popular among users of these respective languages due to the increased productivity they can bring to large and small projects alike.

Yet many PHP developers aren't aware that a similar tool is available for PHP. PHPDocumentor (http://www.phpdoc.org/) is a powerful utility capable of generating documentation from source code comments. Capable of producing documentation in Docbook, HTML, PDF, and Windows Compiled HTML Help formats, PHPDocumentor can go a long way towards taking away the hassle of creating and maintaining end user documentation in a variety of formats. In this article, I'll introduce this great tool, showing you how to structure your code comments in a manner supported by PHPDocumentor, and generate resulting documentation in a format convenient to you.

A Simple Example

PHPDocumentor builds documentation by parsing a comment known as a DocBlock. A DocBlock is a C++-style PHP comment that looks like this:

/** *   This is a DocBlock */

To document a function, you would place a DocBlock directly before the function declaration, like so:

/** * Calculate circumference of circle * * The function circle() calculates the circumference of a circle,  * accepting its radius as input and returning the circumference *  * */ function circle($radius) {     $circumference = 2.0 * 3.14159 * $radius;     return $circumference;      }

This particular DocBlock consists of two items, namely a short and long description. PHPDocumentor knows to separate the two by ending the short description with either a blank line or a concluding period. While the short description is constrained to a maximum three lines, the long description can be as long as is required.

Of course, functions aren't the only language element documentable by PHPDocumentor. You can also document classes, class variables, class methods, define statements, global variables, include/include_once/require/require_once statements, and procedural pages. Let's consider a slightly longer example that demonstrates documentation of several different language elements:

<?php          /**      * Include the Web page template header      */     INCLUDE "pageHeader.inc.php";     /**      * PI calculated to 5 digits      */      define("PI", 3.14159);     /**      * Calculate circumference of circle      *      * The function circle() calculates the circumference of a circle,       * accepting its radius as input and returning the circumference      *       *      */      function circle($radius)      {          $circumference = 2.0 * 3.14159 * $radius;          return $circumference;           }?>

Generating the documentation produces the output shown in Figure 1.

Sample PHPDocumentor Output
Figure 1. Sample PHPDocumentor Output

Tags

In the previous section I introduced you two DocBlock components: the short and long description. There's yet another item that you might wish into a DocBlock, known as a tag. Tags are predefined keywords prefixed with an @ symbol, and they help you create more formal documentation by defining key items of information such as the author, version number, return value, todo items, and copyright. Returning to the circle() function, I'll modify the DocBlock, adding a few tags:

/** * Calculate circumference of circle * * The function circle() calculates the circumference of a circle,  * accepting its radius as input and returning the circumference *  * @author Jason Gilmore  * @param float $radius Radius of the circle * @version 3.2 */

Regenerating the documentation produces the output shown in Figure 2.


Figure 2. Adding tags to your documentation

You can view a complete list of supported tags by navigating to the PHPDoc Documentation.

Dividing Projects Into Packages

Thus far I've based the examples from a single file. While suffice for helping you get acquainted with PHPDocumentor, even simple applications often consist of several files. PHPDocumentor is capable of creating documentation for multiple file projects, done by dividing files and classes into packages. Specifically, constants, functions, and global variables are packaged using a page-level DocBlock, while class variables and methods are packaged using a class-level DocBock. I'll show you how to use packages in the former manner. Let's add a second file to the application, titled square.php:

<?php     /**      * This file contains the square() function.      * @package squarePackage      */     /**      * Include the Web page template header      */     INCLUDE "pageHeader.inc.php";     /**      * Calculate area of a square      *      * The function square() calculates the area of a square,       * accepting the length of each side as input and returning the area      *       */      function square($length)      {          $area = $length * $length;          return $area;      }?>

Note that the page-level DocBlock is placed at the very beginning of the file, and the first item-level DocBlock directly follows it. Also note the reference to @package named squarePackage. Next I'll modify the circle.php file, adding the following page-level DocBlock to the top:

     /**      * This is some file      * @package circlePackage      */ 

Regenerating the documentation produces a table of contents consisting of links to the circlePackage and squarePackage. Clicking on each link will take you to a document similar to that found in Figure 2.

Building the Documentation

You can build the project documentation using the command-line script phpdoc, or a Web-based interface. I'll show you how to use the latter. To begin, download the latest version of PHPDocumentor from the website, extracting it to a protected area of your web document root. I'm presently using version 1.3.0 RC3, which is the first version to be PHP 5 compatible. Then navigate to the index.html file located in the PhpDocumentor directory. You'll see several tabs at the top of the interface, including Introduction, Config, Files, Output, Options, Credit, and Links. Feel free to browse each tab to get an idea of their purpose, however for the purposes of this example you'll need to be concerned with only the Files and Output tabs. Navigate to the Files tab, depicted in Figure 3.

The Files Tab
Figure 3. The Files Tab

Note that you can specify input files in four manner: by file, by directory, files to ignore, and by package. I've added the directory containing the circle.php and square.php files. Next click on the Output tab, depicted in Figure 4.

The Output Tab
Figure 4. The Output Tab

The Target field is used to specify the documentation destination directory. The Output type dropdown lists the variety of templates and documentation types available to you. Throughout this tutorial I've used HTML:Smarty:default. Feel free to experiment with other formats. Add a target directory and press the create button located to the lower-right of the window. You can scroll through the output appearing in the lower frame to review PHPDocumentor's actions. Assuming all goes okay, the output will conclude with "Operation Completed!!". Review your documentation by navigating to the target folder.

Conclusion

In this article I've introduced only a smattering of PHPDocumentor's capabilities, although hopefully this brief article made it apparent that this is one tool you simply can't live without. As always, I welcome questions and comments. Please e-mail me at wj AT wjgilmore.com!

About the Author

W. Jason Gilmore (http://www.wjgilmore.com/) is the Open Source Editorial Director for Apress (http://www.apress.com/). He's the author of Beginning PHP 5 and MySQL: Novice to Professional (Apress, 2004. 748pp.). His work has been featured within many of the computing industry's leading publications, including Linux Magazine, O'Reillynet, Devshed, Zend.com, and Webreview. Jason is also the author of A Programmer's Introduction to PHP 4.0 (453pp., Apress). Along with colleague Jon Shoberg, he's co-author of "Out in the Open," a monthly column published within Linux magazine.

Sitemap | Contact Us

Thanks for your registration, follow us on our social networks to keep up-to-date