@example

The @example tag points at an external source file that demonstrates how to use the element it decorates, so that documentation tooling can display a working sample alongside the API reference instead of leaving readers to piece one together from the description alone. The reference can optionally be narrowed to a specific line range, letting a single illustrating file be reused across several tags that each highlight a different part of it.

"@example" ( <URL> | <URI> )
    [ <StartLine> [ <LinesCount> ] ]
    [ <Description> ]

Parsing an @example tag produces an ExampleTag instance exposing:

$location — the example file's location, as a UriReference.
$start — the starting line of the excerpt, or null when the whole file is meant.
$count — the number of lines to include, or null; only ever set alongside $start.

final class ExampleTag extends Tag
{
    public function __construct(
        string $name,
        public readonly UriReference $location,
        public readonly ?int $start = null,
        public readonly ?int $count = null,
        ?DescriptionInterface $description = null,
    ) {
        parent::__construct($name, $description);
    }
}

@example shares its line-range syntax with @source, but the two point in opposite directions: @example references an external illustrating file, while @source references the documented element's own implementation.

@example is still part of phpDocumentor's current tag reference, not deprecated, but its own page notes that its effects "are not yet fully implemented in phpDocumentor 3" — phpDocumentor tag reference.

05 July 2026