Skip to content

Extending

Definitions

A definition turns a @tag line into a tag. There is one per tag, it declares the grammar of the line and creates the tag from what the grammar matched.

The definition of @param:

final class ParamTagDefinition extends TagDefinition
{
public function __construct()
{
parent::__construct(
name: 'param',
// "@param" <Type> <Variable> [ <Description> ]
spec: Spec::sequence(
Spec::rule(TypeCombinator::NAME, 'type'),
Spec::rule(VariableCombinator::NAME, 'variable'),
Spec::maybe(
Spec::rule(DescriptionCombinator::NAME, 'description'),
),
),
placement: TagPlacement::Block,
);
}
public function create(string $name, TagPayload $result): ParamTag
{
return new ParamTag(
name: $name,
statement: $result->get('type'),
variable: $result->get('variable'),
description: $result->find('description'),
);
}
}
Argument Value
name the name of the tag, without the @
spec the grammar of the line after the name
placement where the tag may be written, see below

create() gets a TagPayload with the values the grammar captured and returns the tag.

A line that does not match the spec never reaches create(): it becomes an InvalidTag.

A tag without a definition is read by GenericTagDefinition: the whole line becomes the description of a plain Tag. A TagFactory built by hand takes a createUnknownTagDefinition closure to read such tags another way.

enum TagPlacement
{
// inside a description: {@tag ...}
case Inline;
// on a line of its own
case Block;
// both, the default
case Any;
}
Placement Built-in tags
Any @see, @link, @internal, @example
Inline @inheritdoc, @source
Block every other tag

An inline tag is parsed into the same tag object as a block one.