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 |
Building the tag
Section titled “Building the tag”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.
Unknown tags
Section titled “Unknown tags”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.
Inline tags
Section titled “Inline tags”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.