phpDocumentor

What is a DocBlock?

Overview

The goal of this tutorial is to introduce you to writing and subsequently generating effective documentation with phpDocumentor.

Writing a DocBlock

A DocBlock is a piece of documentation in your source code that informs you what the function of a certain class, method or other Structural Element is.

What can be documented in your source code?

Before we discuss what a DocBlock looks like, let's first zoom in on what you can document with them. phpDocumentor follows the PHPDoc definition and recognizes the following Structural Elements :

In addition to the above, the PHPDoc standard also supports DocBlocks for Files and include /require statements, even though PHP itself does recognize this as a language structure.

Each of these elements can have exactly one DocBlock associated with it, which directly precedes it. No code or comments may be between a DocBlock and the start of an element's definition.

What does a DocBlock look like?

DocBlocks are always enclosed in a particular comment-type, called a DocComment . A DocComment starts with /** (opener) and ends with */ (closer). Each line in between the DocComment opener and its closer should start with an asterisk (* ).

For example:

<?php
/**
 * This is a DocBlock.
 */
function associatedFunction()
{
}

File-level DocBlocks

Quite often projects will also want to document the license or role for an entire file. This can be accomplished by having a DocBlock as the first element encountered in a file. It is important to note that whenever another Structural Element directly follows the DocBlock, it is no longer recognized as a File-level DocBlock, but as belonging to the subsequent element.

The following DocBlock is a File-level DocBlock:

<?php
/**
 * I belong to a file
 */

/**
 * I belong to a class
 */
class Def
{
}

In contrast, in the following example the DocBlock belongs to the class:

<?php
/**
 * I belong to a class
 */

class Def
{
}

DocBlocks are divided into three parts. Each of these parts is optional, except that the Description can not exist without a Summary .

Summary

The Summary, sometimes called a short description, provides a brief introduction into the function of the associated element. A Summary ends when it encounters either of the below situations:

  • a period . , followed by a line break
  • or a blank (comment) line.
Description
The Description, sometimes called the long description, can provide more information. Examples of additional information are: a description of a function's algorithm, a usage example or a description of how a class fits in the whole of the application's architecture. The description ends when the first tag is encountered on a new line or when the DocBlock is closed.
Tags and Annotations
These provide a way to succinctly and uniformly provide meta-information about the associated element. Tags can, for example, describe the type of information that is returned by a method or function. Each tag is preceded by an at-sign (@ ) and starts on a new line.

Example

A DocBlock looks like this:

<?php
/**
 * A summary informing the user what the associated element does.
 *
 * A *description*, that can span multiple lines, to go _in-depth_ into
 * the details of this element and to provide some background information
 * or textual references.
 *
 * @param string $myArgument With a *description* of this argument,
 *                           these may also span multiple lines.
 *
 * @return void
 */
 function myFunction($myArgument)
 {
 }

Let's go through this example line by line and discuss which is which,

Line 2 :
shows that a DocBlock starts with the opening sequence /** .
Line 3 :
has an example of a Summary. This is, usually, a single line but may cover multiple lines as long as the end of the summary, as defined in the previous chapter, is not reached.
Line 5 , 6 and 7 :
show an example of a Description, which may span multiple lines and can be formatted using the Markdown markup language. Using Markdown you can make text bold , italic , add numbered lists and even provide code examples.
Line 9 and 12 :
show that you can include tags in your DocBlocks to provide additional information about the succeeding element. In this example, we declare that the argument $myArgument is of type string , with a description what this argument represents, and we declare that the return value for this method is void , which means that no value will be returned.
Line 13 :
shows the closing sequence */ , which is the same as that for a multi-line comment (/* .. */ ).

If you'd like to know more about what DocBlocks do for you, visit the chapter More on DocBlocks for more in-depth information.

Read more

  • Generating documentation, now that you have learned what a DocBlock looks like, shall we take phpDocumentor for a spin?
  • Configuration, there are a lot more options to phpDocumentor. To maintain consistent documentation, it is good practice to define them all in a configuration file and to include that in your project.
  • Running phpDocumentor, if you'd like to know more on the options available when using phpDocumentor; see the guide for more information.

Search results