Pro PHP- Patterns, Frameworks, Testing and More

CHAPTER 6 ■ DOCUMENTATION AND CODING CONVENTIONS^59

Using metadata in this way is especially useful in generating documentation automatically.

One method of creating manuals from metadata is to use the PHPDoc standard. If you create

doccomments that follow a specific format, a parser program can turn the comments into

meaningful documentation automatically.

PHPDoc

PHPDoc (http://www.phpdoc.org/) is the most widely used solution for maintaining PHP

documentation. If you’ve ever used a PEAR library or any kind of prepackaged PHP library,

you will have undoubtedly run across PHPDoc.

PHPDoc defines a structure for doccomments that allows them to be parsed in a consis-

tent manner. As HTML is to XML, PHPDoc is to doccomments. With it, you can create useful

manuals from your in-line documentation.

PHPDoc consists of a set of rules regarding how to declare doccomments and is almost a

language in itself. A PHPDoc block—a doccomment—can define dozens of different pieces of

metadata. In this section, I’ll cover only the basics and most commonly used parts of PHPDoc.

Like all doccomments, PHPDoc blocks must start with the slash-star-star comment declara-

tion. Next, they may include normal descriptive information about the item you are documenting.

/**

I am a PHPDoc comment and I describe somefunction

*/

function somefunction() {}

This follows the format of all doccomments, so you are likely wondering what makes it

special. The answer is tags!

Tags are specified by the @ symbol and a predefined identifier. They can occur at the begin-

ning of a line or may be enclosed in curly braces ({}) and placed free-form anywhere within the

comment. The allowable identifiers are predefined, and they form the rules for how a docu-

mentation parser will interpret your comments.

/**

I am a PHPDoc comment.

@param bool $foo Foo tells the function something

*/

function bar($foo) {}

Notice that a @param tag describes the function’s $foo argument. This is metadata and can

later be read by a parser to output documentation about $foo. The tag’s format allows you to

add some extra metadata, such as the type of the variable, the variable’s name, and a descrip-

tion of what it does. All PHPDoc tags follow this same basic format.

The @param tag is just one tag of many. Table 6-1 lists the most commonly used PHPDoc

tags applicable to PHP 5 and later. For the complete list, see http://manual.phpdoc.org/.

■Note Some of the PHPDoc tags in the official standard are not applicable when working with reflection-

based parsers because these parsers can determine some attributes, like access, automatically.

McArthur_819-9C06.fm Page 59 Friday, February 22, 2008 8:59 AM