Pro PHP- Patterns, Frameworks, Testing and More

CHAPTER 6 ■ DOCUMENTATION AND CODING CONVENTIONS^57

PHP Comments and Lexing

To get the most from your documentation efforts, it is important to understand the differences

between different types of comments. Some types of comments just include information for

programmers, and other types actually store their content with the program’s data.

Types of Comments

PHP has several types of comments. Single-line comments are declared like this:

//This is an inline comment

Multiline comments have the following form:

/*

This is a multiline comment and

may span many lines

*/

A third form is known as a doccomment, which is declared like this:

/**

This is a doccomment, which is also often

called a docblock

*/

The two latter forms might look similar, but they have different parsing implications to

PHP. The first form is just human-readable information that is not meaningful to PHP. The

second form does something extra: it stores the data of the comment along with the program

code, and this data may be used by other applications to get more information about how they

should interact with your program. Let’s take a closer look at how doccomments work.

More About Doccomments

Doccomments can be associated with certain programming elements, such as classes, func-

tions, constants, variables, methods, and so on. To associate a doccomment with an element,

you simply declare the doccomment block immediately prior to the element and ensure that

there are no newlines between the closing asterisk (star) and slash and the element. Listing 6-1

demonstrates how to associate a doccomment with a function.

Listing 6-1. Using Doccomments

/**

This is a doccomment that is associated with a function

*/

function notimportant() {}

/*

This is not a doccomment because it does not start with a slash-star-star

*/

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