Skip to content

Overview

Reading a comment

A comment is split into a description and one segment per tag, then each segment is parsed by the grammar of its tag.

$block = $parser->parse(<<<'PHPDOC'
/**
* Sends a message, see {@see Mailer::send()}.
*
* @param list<User> $users The recipients.
* @return bool
*/
PHPDOC);

A DocBlock holds the description and the tags, and is itself a list of its tags:

$block->description; // TaggedDescription
$block->tags; // [ParamTag, ReturnTag]
count($block); // 2
$block[0]; // ParamTag
foreach ($block as $tag) {
// ...
}

Everything before the first tag. A plain text is a Description with a $value, a text with inline tags is a TaggedDescription: a list of texts and tags.

Sends a message, see {@see Mailer::send()}.
└─────────┬─────────┘└────────┬──────────┘│
Description SeeTag Description
(string) $block->description; // "Sends a message, see {@see Mailer::send()}.\n"
$block->description->tags; // [SeeTag]
foreach ($block->description as $part) {
// Description, SeeTag, Description
}

Any {@name ...} with balanced braces is an inline tag, parsed by the same definition as a block tag of that name. Which tags are meant to be inline is told by their placement.

Every tag has a $name without the @ and an optional $description. A tag known by its name adds its own parts:

$param = $block[0]; // ParamTag
$param->name; // 'param'
$param->type; // TypeNode of `list<User>`
$param->variable; // 'users'
$param->description; // Description of 'The recipients.'

A tag without a definition, such as one marked “Not Implemented” in the sidebar, is a plain Tag: the whole line is its description.