Using phpDoc

"phpDocumentor" (phpDoc) is used for documenting source code. TYPO3 code typically uses the following phpDoc keywords:

  • @global
  • @param
  • @return
  • @see
  • @var
  • @deprecated

For more information on phpDoc see the phpDoc web site at https://www.phpdoc.org/.

TYPO3 does not require that each class, function and method be documented with phpDoc.

But documenting types is required. If you cannot use type hints then a docblock is mandatory to describe the types..

Additionally you should add a phpDoc block if additional information seems appropriate:

  • An example would be the detailed description of the content of arrays using the Object[] notation.
  • If the return type is mixed and cannot be annotated strictly, add a @return tag.
  • If parameters or return types have specific syntactical requirements: document that!

The different parts of a phpDoc statement after the keyword are separated by one single space.

Class information block

((to be written))

((was: For information on phpDoc use for class declarations see "Class information block".))

Function information block

Functions should have parameters and the return type documented. Example:

/**
 * Initializes the plugin.
 *
 * Checks the configuration and substitutes defaults for missing values.
 *
 * @param array $conf Plugin configuration from TypoScript
 * @return bool true if initialization was successful, false otherwise
 * @see MyClass:anotherFunc()
 */
protected function initialize(array $conf) : bool
{
    // Do something
}

Short and long description

A method or class may have both a short and a long description. The short description is the first piece of text inside the phpDoc block. It ends with the next blank line. Any additional text after that line and before the first tag is the long description.

In the comment blocks use the short forms of the type names (e.g. int, bool, string, array or mixed).

Use @return void when a function does not return a value.