phpDocumentor

@param

The @param tag is used to document a single argument of a function or method.

Syntax

@param [<Type>] [name] [<description>]

Description

With the @param tag it is possible to document the Type and the intent of a single argument of a function or method. When provided it MAY contain a Type to indicate what is expected. The name of the argument MUST be present so that it is clear which argument this tag relates to.

The description is OPTIONAL yet RECOMMENDED, for instance, in case of complicated structures, such as associative arrays.

The @param tag MAY have a multi-line description and does not need explicit delimiting.

At a minimum, it is RECOMMENDED to use this tag with each argument whose code signature does not provide Type information.

This tag MUST NOT occur more than once per argument in a PHPDoc and is limited to Structural Elements of type method or function.

Effects in phpDocumentor

Structural Elements of type method or function, that are tagged with the @param tag, will have additional information in the section regarding Parameters.

If the parameter Type is a class that is documented by phpDocumentor, then a link to that class' documentation is provided.

phpDocumentor will not verify whether a documented type is in line with a declared type. Such verification, if desired, can be executed by static analyzer tools like PHPStan, psalm or PHP_CodeSniffer.

Examples

Here is a fully formed example, where all arguments are given param tags even when not strictly required.

/**
 * Counts the number of items in the provided array.
 *
 * @param mixed[] $items     Array structure to count the elements of.
 * @param bool    $recursive Optional. Whether or not to recursively
 *                           count elements in nested arrays.
 *                           Defaults to `false`.
 *
 * @return int Returns the number of elements.
 */
function count(array $items, bool $recursive = false)
{
    <...>
}

Search results