Writing Self-Documenting PHP Code - Drilling Deeper
(Page 3 of 7 )
As you can see from the example on the previous page, a general overview of the class is provided in the comment block preceding the class definition.
<?php
/**
* Automatically creates a sandwich customized to your preferences
*
* @author Melonfire <melonfire@mail.com>
* @version 2.0
* @since 1.3
* @access public
* @copyright Melonfire
*
*/
class SandwichMaker()
{
// snip
}
?>
The first line within the comment block provides a brief,
human-readable description of the class. It is followed by a blank line, and a series of tags.
Each of the tags in the comment block above provides information on some aspect of the class. Here's a brief list of what they represent:
@author - the name of the class author
@version - the current version number of the class
@since - historical information on the availability of this class
@access - whether this class is a private or public class
@copyright - the name of the copyright holder of the class
Most of these tags are optional; PHPDoc will either use default values if they are not present, or simply ignore their absence.
If a class has multiple authors, you may list them using multiple @author tags - remember to group them together so that the parser has no difficulty finding all of them.
If you would like to group your classes together, you can also use the
@package package-name
tag as a grouping key; PHPDoc will then use the package name
to group all related classes together when creating the documentation.
Moving on, once the class has been documented, the next step is to document the class variables. Here's an example:
<?php
/**
* Bread type
*
* @var integer
* @access public
* @see setType()
*/
var $type;
?>
In addition to the tags described above, class variables can
have two additional tags, both of which are fairly self-explanatory:
@var - the variable type
@see - references to other, related variables and methods
Finally, all that's left is to document the class methods. Here's a quick example,
<?php
/**
* Sets bread type for sandwich
*
* @param integer $type bread type
* @return Boolean
* @access public
* @see makeSandwich()
* @see setFillings()
*/
function setType($type)
{
// snip
}
?>
Class methods can use two additional tags, in addition to the
ones previously described:
@return - a description of the return value from the method
@param - a description of the argument passed to the method, in the form
@param arg-type arg-name arg-description
Obviously, you should include as many @param tags as there
are arguments to be passed to the method, and you should make it a point to list them in the order in which the method expects them.
It should be noted that the @see tag is particularly useful when it comes to documenting class methods - it provides an easy way to create connections between related methods. PHPDoc will automatically hyperlink the methods named in the @see tag to each other when it creates the documentation.
Next: I, Robot >>
More PHP Articles
More By Harish Kamath, (c) Melonfire
/ 13 
