CHAPTER 6 ■ DOCUMENTATION AND CODING CONVENTIONS^61Listing 6-2 demonstrates a typical PHPDoc comment on a function.Listing 6-2. A PHPDoc Comment on a Function/**
* This function adds two strings.
*
* It does this by taking the first string and
* adding it to the second string, and
* then returns the result.
*
* @param string $string1 The left string.
* @param string $string2 The right string.
* @return string A string containing concatenated inputs.
* @todo Add a joining character parameter.
*/
function concatTwoStrings($string1,$string2) {
return $string1. $string2;
}OK, so now that you have all these documentation blocks and tags, how do you use them
to create a manual? One option is to use the phpDocumentor parser; another is to parse the
information using reflection. Reflection will be covered in the next chapter. Here, let’s see how
to use phpDocumentor.@see reference Refers to the documentation of another element. You
can use a variety of pointers, including a file, function
name, class method, and many more. Multiple values
can be separated by commas. This tag may also be
used in-line.
@since version [information] Allows you to tag the version in which this element
first appeared.
@source startoffset [endoffset] Allows you to include some of the source code for an
associated element in-line with the documentation
(the tag is in-line only). The start offset is the offset
line number you want to include in your documenta-
tion, and the end offset is the number of lines you
wish to include. If you omit the end offset, all the code
starting at the start offset until the end of the element
will be included.
@todo description Includes information about work that remains to be
done or a problem that needs to be resolved.
@var datatype Documents the type of class variables that are also
known as properties.
@version Specifies the current version number of an element.Table 6-1. Common PHPDoc Tags
Tag DescriptionMcArthur_819-9C06.fm Page 61 Friday, February 22, 2008 8:59 AM