PHP Doc Comment - SyntBlaze

A PHP Doc Comment (commonly referred to as a DocBlock or PHPDoc) is a specialized block comment used to annotate structural elements in PHP code, such as classes, interfaces, traits, methods, functions, and properties. It provides a standardized, machine-readable format for describing the signature, types, and behavioral characteristics of the associated element, which is subsequently parsed by the PHP Reflection API, static analysis tools, and IDEs. A valid DocBlock must begin with a forward slash followed by exactly two asterisks /** and end with an asterisk followed by a forward slash */. Every line within the block must be prefixed with an asterisk *.

/**
 * Short summary of the structural element.
 *
 * A more detailed description that can span multiple lines.
 * It provides technical specifics about the element's behavior.
 *
 * @param string $identifier The unique identifier.
 * @return bool True on success, false on failure.
 */
function processIdentifier(string $identifier): bool {
    // ...
}

Structural Components

A standard DocBlock is divided into three distinct sections, separated by blank lines (lines containing only the prefix asterisk):

Summary: A single, concise line summarizing the element. It is terminated by a period or a blank line.
Description: An optional, multi-line block providing detailed technical information. Markdown is often supported within this section by modern parsers.
Tags: A collection of meta-data annotations, always prefixed with an @ symbol, defining specific attributes like parameter types, return types, and exceptions.

Core Tags and Syntax

Tags follow a strict syntax, generally structured as @tagName [Type] [Variable] [Description].

@param: Defines the expected type and description of a function or method argument.

/**
 * @param int $timeout Connection timeout in seconds.
 */

@return: Defines the type and description of the value returned by a function or method.

/**
 * @return array<string, mixed> The parsed configuration array.
 */

@var: Documents the type of a class property or a local variable.

/**
 * @var PDO The active database connection instance.
 */
private PDO $connection;

@throws: Indicates the specific exception types that the element might throw during execution.

/**
 * @throws InvalidArgumentException If the provided payload is malformed.
 */

Type Expressions

PHPDoc allows for complex type definitions that exceed PHP’s native runtime type hinting capabilities. These expressions are heavily utilized by static analyzers (like PHPStan or Psalm).

Primitives: int, float, string, bool, null, mixed, void, object, callable, resource.
Arrays: Appending [] to a type (e.g., int[], User[]).
Union Types: Separated by a pipe | to indicate multiple acceptable types (e.g., string|null, int|float).
Intersection Types: Separated by an ampersand & to indicate an object must satisfy multiple types (e.g., Countable&Traversable).
Generics: Using angle brackets to define the types of keys and values within collections (e.g., array<int, string>, Collection<User>).

Reflection API Integration

At runtime, PHP does not execute or enforce the contents of a DocBlock. However, the PHP engine stores these comments in memory, making them accessible via the Reflection API. Developers can programmatically extract DocBlocks using the getDocComment() method on reflection objects.

$reflection = new ReflectionFunction('processIdentifier');
$docBlock = $reflection->getDocComment();

// $docBlock now contains the raw string of the /** ... */ comment