Your First Set of Documentation¶

Which elements can be documented?¶

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

• Function
• Constant
• Class
• Interface
• Trait
• Class constant
• Property
• Method

In addition to the above the PHPDoc standard also supports DocBlocks for Files and include/require statements, even though PHP itself does not know this concept.

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 comment-type, called DocComment, that starts with /** and ends with */. Each line in between the opening and closing statement should start with an asterisk (*). Every DocBlock precedes exactly one Structural Element and all contents of the DocBlock apply to that associated element.

For example:

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

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

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

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

class Def
{
}

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

Summary

Sometimes called a short description, provides a brief introduction into the function of the associated element. A Summary ends in one of these situations:

1. A dot is following by a line break, or
2. Two subsequent line breaks are encountered.

Description

Sometimes called the long description, can provide more information. Examples of additional information is a description of a function’s algorithm, a usage example or description how a class fits in the whole of the application’s architecture. The description ends when the first tag is encountered or when the DocBlock is closed.

Tags and annotations

These provide a way to succinctly and uniformly provide meta-information about the associated element. This could, 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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

 <?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 and 6

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 8 and 11

show that you can include tags with 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 there is no value returned.

Line 12

shows the closing statement */, which is the same as that for a multiline comment (/* .. */).

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