Section B.2. Documentation Comments

B.2. Documentation Comments

The phpDocumentor tool generates documentation of the elements in your sources. The documentation is embedded in the source as comments. Nine distinct types of sections are understood by the tool: global variable, include, constant, function, define, class, variable, method, and page.

Every file inside your PHP project that you're going to process with phpDocumentor should start with a page level docblock, which documents certain aspects (like the author, package name, and so on) of this specific file. A docblock always starts with the sequence /**, unlike "normal" comments that usually start with only /*:

 <?php /**  * Page level docblock  * @author Derick Rethans <[e-mail]>  * @package Examples  */ 

After this page-level docblock, which always should exist before any other docblock, you can start documenting the other elements. So, our file continues with something like

 /**  * Example element-level docblock for a function  *  * @return mixed  */ function foo() { } 

Before every element in a docblock, a special formatted tag is placed which will be picked up by the tool. All tags in phpDocumentor comments begin with an @. The general format of a phpDocumentor comment looks like this:

 <?php /** * Short description * * Long description * * @keyword1 parameter1 parameter2 ... parameter n * @keyword2 parameter1 parameter2 ... parameter n */ { element to describe } ?> 

The short description should only occupy one line in the comment. A line is everything between the * and newline character sequence. With the short description, you can describe what this specific element does. For example, you can say "Encrypts a file with the Rijndael cipher" or "Makes an MD5 sum of a string." The short description is used in the index and the contents in the generated documentation.

With the long description, you can describe your element in more detail. You can discuss where the documented element originated, which properties it has, and on which things it relies; you can also include examples on how to use the element. The detailed description of the element can include HTML tags. phpDocumentor supports the following HTML tags:

 <b> <br> <code> <i> <kbd> <li> <ol> <pre> <samp> <var> <ul> 

After the descriptive elements in the comment, the keyword section follows. The keyword section describes pre-defined elements of your source code element. The following sections explain all available tags, and because not all keywords are available for every type of element in a source file, it also gives you information in which of the nine different elements the keyword is supported.