PhpDocumentor
จาก Wiki2
เนื้อหา |
Documenting PHP Code with PHPDocumentor
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
/**
* Short description
*
* Long description
*
* @tagskeyword1 parameter1 parameter2 … parameter n
* @tagskeyword2 parameter1 parameter2 … parameter n
*/
{ element to describe }
----
/**
* 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;
}
?>
Tags
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 */
Dividing Projects Into Packages
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
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 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!
Ref: http://www.developer.com/lang/php/article.php/3440261/Documenting-PHP-Code-with-PHPDocumentor.htm
