Getting Started with PHP DocBlox Code Comments

Code commenting is a very important part of the entire development process. Large blocks of functions and variable declarations can get bloated down after writing pages of convoluted backend logic. PHP is one such language where keeping your code comments organized will most certainly help later on down the road.

PHPDoc also called PhpDocumentor is a type of code commenting system where you can fill in all the most important details for any function or class. This becomes very useful when looking back over codes trying to determine what they actually do. The formatting is really easy, and even without an automated program you can still write DocBlox syntax with ease. I hope this introductory guide may offer some tips and advice for beginners.

Getting Started

phpDocumentor was the original project which was then upgraded to phpDocumentor 2. The new homepage is called the DocBlox Project and it still supports all the same original syntax from the 1st version.

You write DocBlox comments by using multi-line comments with an asterisk preceding each line. This formatting will help each comment to stand out from the rest of your code. It is very noticeable and these comment blocks fit nicely right above your function definitions. There are 3 main sections of the comment known as short description, full description, and tags. Take a peek at this example code from a tutorial on PHP Master:

/**
 * Calculates sum of squares of an array
 *
 * Loops over each element in the array, squares it, and adds it to 
 * total. Returns total.
 * 
 * This function can also be implemented using array_reduce();
 * 
 * @param array $arr
 * @return int
 * @throws Exception If element in array is not an integer
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}

All of these areas in the comment are optional. The short description should be a 1-2 sentence statement explaining what the function actually does. It can be written any way you like as long as each new line is preceded with an asterisk. Separate your short and full descriptions with a space in-between. The full description can be multiple paragraphs if needed. But remember that documentation should be short, sweet, and easy to follow.

/**
 * Automatically capitalize the first letter of a string
 */
function capMyWords($string) { /* code here */ }

Understanding Tags

So far the whole concept of phpDoc/DocBlox should be very simple. You open a multi-line comment block for the sole purpose of explaining how your function/class operates. Each new line is preceded by an asterisk and you want to keep descriptions short but understandable.

The next important idea you should learn are called tags. These tag lines also include an asterisk but the tag name itself should be preceded by an @ symbol. There is such a long list of tags I couldn’t possibly fit them all into this article. Nor will you need to use them all, but if you are interested check out the phpDoc online documentation for a list of commonly-used tags. Here is a small example:

/**
 * A simple tags demonstration
 * @return string
 * @author Your Name Here
 * @version 1.0
 */

So the @tag syntax may be seen as a way to catalog and organize important bits of information. Each function will generally take some form of parameters and then returns some type of data. You should get into the habit of specifying this in your comments for each function. It will make editing a lot easier in the future if you know exactly what the function expects and what it returns.

Many times you will have a function with multiple parameters. Your lengthy DocBlox comments may take up a lot of space in the file, but it is worth it just to stay organized. Programming is difficult so why make things even harder? Check out this great example from a SlideShare presentation which outlines a more detailed comment block.

/*
 * This is a short description.
 *
 * This is a long description, which may
 * span multiple lines and even holds @inline tags.
 * 
 * @param string $a The first awesome variable
 * @param string $b The second awesome variable
 * @param array  $arr An assoc array of key/value pairs
 *
 * @return boolean
 */
function SomeFunction($a, $b, $arr) {
}

Moving Beyond Functions

DocBlox can be used to leave comments for other code elements in your file aside from just functions. Even the file itself may use some type of DocBlox commenting. Developers who are familiar with WordPress may remember seeing this syntax in the default theme files. For example here is the top comment from 404.php in the Twenty Twelve theme.

/**
 * The template for displaying 404 pages (Not Found).
 *
 * @package WordPress
 * @subpackage Twenty_Twelve
 * @since Twenty Twelve 1.0
 */

The tag @package is a way to reference other packages or files which are included in the current file as a dependency. @subpackage is similar where you can reference alternate packages that also rely on the first package declaration. To organize your files in this manner is slightly unnecessary, unless you are working within a CMS like WordPress.

But when coding your own PHP files from scratch it is often a bit overkill. Unless you really like the idea of documenting every aspect of your code. However the best way to get familiar with DocBlox commenting is to just practice. It will appear confusing at first – especially when trying to memorize all the important tags. But stick to it and eventually you can be writing beautiful PHP code almost effortlessly.

Auto-Generating Comments

There are two notable programs written to help with automating the documentation process. I really do not like to use automated stuff because I prefer hard-coding within an IDE. Especially when editing a CMS file because you never know how the syntax may clash with other files.

The phpDox project on Github can be used to install the Documentation software, and to automate the coding process. There is a guide on the Github wiki explaining how to run these commands right from the terminal window. But another choice is the original phpDocumentor2 which can be found on Github or on its own website.

Ultimately running either of these programs will help you learn the syntax quickly. The built-in libraries and commands within the terminal window are masterful. But other PHP developers may rather study the syntax and use it manually in various bits of code. Either way DocBlox code commenting is a topic worth studying if you plan on getting serious with PHP.

Final Thoughts

If you are already familiar with code commenting then the switch over to DocBlox should not be much of a hassle. In fact, it should feel a bit relieving to know that you can follow a familiar structure in all your comments. PHP is quite a verbose language with a lot of heavy syntax. There will be times coming back to an old script or WordPress theme where you can really put these comment blocks to good use. Along with my resources feel free to share your own thoughts in the post discussion area below.