August 28, 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 »

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.





Page 2 of 2



Comment and Contribute

 


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

 

 


Sitemap | Contact Us

Rocket Fuel