Skip to content

Tag reference

@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.

Grammar

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

Examples

Pointing at an entire example file.
/**
* @example docs/examples/mailer-basic.php
*/
public function send(Message $message): bool
Narrowed to the lines that show the relevant usage.
/**
* @example docs/examples/mailer-retry.php 12 8 Configuring a retry
* policy.
*/
public function withRetries(int $attempts): static

Names by platform

phpdocumentor
@example

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.