What is a DocBlock?

A DocBlock is a multi-line C-Style comment used to document a segment or element of code. It begins with /** and has an asterisk at the start of each line; as shown here:

[cc lang=php”]
/**
* Dispatch Controller Class
*
* @uses \Bluewater\Http_Uri getInstance()
* @uses \Bluewater\Controller_Command getInstance()
* @uses \Bluewater\Dispatcher $_objCommand
* @uses \Bluewater\Dispatcher $_loadController()
*
* @static
* @final
* @access public
*
* @PHPUnit Not Defined
*
* @param void
* @return void
*/
[/cc]

Format of a phpDoc DocBlock

DocBlocks consist of distinct two sections: short and long descriptions and phpDoc block tags. Each section is optional.

  1. Description Block
    • Single, short, succinct summary; ending at the first PERIOD.
    • Complete description
  2. Block Tags

Description

A phpDoc description can be written in plain text or embellished with HTML [v4.1] tags markdown format. A description block must be at the top of each file, precede each class, each method of a class, every class property and constant declaration.

The first part of the description block is the summary, a single sentence containing a concise but comprehensive description of the API item. This “first sentence” is defined as “any text up and including the first period.” And this does mean “first period,” so be mindful. This short summary is automatically placed in the class/method summary table (and index).

Place a blank line between this summary sentence and a more complete description. This is more for a visual separation, namely: a person reading the code. The phpDoc ignores this blank line between the descriptors.

A full description should outline the features, requirements, expectations and specify any dependencies where necessary of the API item. This description can be written in plain text or embellished with HTML [v4.1] tags markdown format.

If there is more than one paragraph in the phpDoc long description block, separate the paragraphs with a blank line.

Example

[cc lang=php”]
/*
* This is a single sentence descriptor.
*
* This is a multi-line description
* that spans several lines.
*
* This is another paragraph. Notice the blank line above.
*/
[/cc]

Tag Block

The Block Tags section of a DocBlock contain 1 or more of special tags denoted by the @ symbol. The tags are used to specify additional information, such as the expected parameters and their type. These tags must be on their own line. The exception are inline tags discussed below. The complete list of Block Tags can be found on the phpDoc Tags page.

An @param tag is “required” (by convention) for every parameter, even when the description is obvious. Even if the method/function does not have an argument list.

The @return tag is required for every method, even if the method/function does not return anything.

Example

[cc lang=php”]
*
* @param boolean $_processSections determine whether to process individual sections
*
* @return object $_controller New Controller Object
*
[/cc]

[cc lang=php”]
*
* @param void
*
* @return void
*
[/cc]

These principles expedite automated searches and processing. Also, a little effort to with what may seem like obvious information pays off in extra clarity for other developers.

Tags should be in a particular, somewhat logical order or pattern.

When the same tag appears more than once in a phpDoc block, each group of tags, such as multiple @uses tags, should be separated from other tags by a blank line with a single asterisk, as this example shows.

[cc lang=php”]
*
* @uses \Bluewater\Config
* @uses \Bluewater\DB\Table_Adapter
*
* @requires \Bluewater\DB
*
[/cc]

  • Multiple @contributor tags should be listed in chronological order, right after the @author tag which defines the creator of the class.
  • Multiple @param tags should be listed in argument-declaration order. This makes it easier to visually match the list to the declaration.
  • Multiple @throws tags (also known as exception) should be listed alphabetically.

As with any good system, it allows for extensions and customization. phpDocumenter is no different.

I have defined a few “custom” tags within this collection. Your copy of phpDocumenter will have to be updated to understand these new tags and process them. Assuming you wish to generate your own copy of the API docs.

See the complete phpDocumentor Tags list for these custom tags.

  1. No comments yet.
(will not be published)

Why ask?