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.

Next: Drilling Deeper >>
 

More PHP Articles
More By Harish Kamath, (c) Melonfire

Comments On: Writing Self-Documenting PHP Code

>>> Be the FIRST to comment on this article!