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.
/ 14 
