October 25, 2014
Hot Topics:
RSS RSS feed Download our iPhone app

Documenting PHP Code with PHPDocumentor

  • November 24, 2004
  • By W. Jason Gilmore
  • Send Email »
  • More Articles »

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.



Page 1 of 2



Comment and Contribute

 


(Maximum characters: 1200). You have characters left.

 

 


Sitemap | Contact Us

Rocket Fuel