Writing Self-Documenting PHP Code - Speaking In Tongues (
Page 2 of 7 )
PHPDoc is based on
Javadoc, the trailblazing documentation standard for Java application code.
Javadoc began as in-house effort at Sun Microsystems to ensure consistency in
code documentation; it rapidly turned into an unofficial standard used by
millions of Java programmers worldwide.
According the Javadoc site (
http://java.sun.com/j2se/javadoc/),
"...the Javadoc tool parses the declarations and documentation comments in a set
of Java source files and produces a corresponding set of HTML pages describing
(by default) the public and protected classes, nested classes (but not anonymous
inner classes), interfaces, constructors, methods, and fields..."
Ouch!
Why can't these guys speak plain English?!
Let me translate: Javadoc is a
tool that reads and parses the comments within the source code of a Java
package, and automatically converts these comments into human-readable API
documentation. Obviously, the process is not completely automatic - the
developer still needs to follow some basic rules while creating the comments -
but using Javadoc to generate API documentation is still faster than doing it
manually.
PHPDoc is similar to Javadoc. It, too, uses comments (in the
same style employed by Javadoc) placed within a class' source code to
automatically and transparently create API documentation that can be delivered
to a customer together with the source code. It doesn't do everything Javadoc
can do, primarily because PHP is a far simpler language than Java and the
additional complexity is not really necessary; however, as you will see, it
packs more than enough power for most purposes.
Before I get into the
nitty-gritty of using PHPDoc, I'm going to quickly review the basics of the
comment style used, so that you have a better understanding of the concept and
how it works. Flip the page, and let's get started. {mospagebreak title=A Quick
Snack} PHPDoc requires that the comments placed by a developer within his or her
source code conform to a particular format. Assuming this format, PHPDoc can
parse these comments and use them to create an API document.
In order to
demonstrate this, let's consider the following simple PHP class, which claims to
automatically make a sandwich for you. This class has been marked up with
PHPDoc-compatible comments.
<?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
{
/**
* Bread type
*
* @var integer
* @access public
* @see setType()
*/
var $type;
/**
* Sandwich filling
*
* @var array
* @access public
* @see setFillings()
*/
var $fillings = array();
/**
* Creates a sandwich with specified bread type and filling
*
* @return Boolean
* @access public
*/
function makeSandwich()
{
// snip
}
/**
* Sets bread type for sandwich
*
* @param integer $type bread type
* @return Boolean
* @access public
* @see makeSandwich()
* @see setFillings()
*/
function setType($type)
{
// snip
}
/**
* Sets filling for sandwich
*
* @param array $fillings list of fillings
* @return Boolean
* @access public
* @see makeSandwich()
* @since 1.2
*/
function setFillings($fillings)
{
// snip
}
}
?>
There are some fundamental rules you should be aware of when
creating these comment blocks:
1. Every comment block must begin with a
forward slash (/) followed by two asterisks (**).
2. Subsequent lines
begin with an asterisk (*), which is indented to appear under the first asterisk
of the opening line.
3. The end of the block is defined by an asterisk
(*), followed by a forward slash (/).
Such comment blocks are usually
present at both package and module level in Java. Since PHP does not group
objects in this way, you don't usually have to worry about these (although you
can, if your code is organized according to this convention).
Once you've
got the initial comment block set up, PHPDoc lets you add some information to
it. This information consists of a single-line description of the item, together
with zero or more tags containing further information. The description and tags
are separated by a single line containing a single asterisk (*).
Each
Javadoc "tag" consists of the @symbol, a keyword and a value. For example, the
tag
@author Melonfire <melonfire@mail.com>
when used in a class context, indicates that the class was
created by Melonfire, while the tag
@version 2.0
indicates that the class is currently at version
2.0
There are three types of comment blocks you may use here:
1.
Class comment block: This comment block provides a general overview of the
class, its purpose, its authors and its version number. It typically appears
right at the top of the class definition.
2. Variable comment block: This
comment block is used to document class variables or properties; it provides
information on the variable type, its raison d'etre, and references to other
class variables that it is related to.
3. Method comment block: This
comment block documents class methods, providing detailed information on method
arguments, return values and public/private access.
Let's look at each of
these in detail.
/ 14 
