DocBlock

Parses PHPDoc/docblock comments into structured data.

class DocBlock

Instances expose the parsed brief and detailed descriptions, plus all tag values keyed by tag name.

Properties

vectors

Tags in the docblock that have a whitepace-delimited number of parameters

private array $vectors = array (
  'param' => 
  array (
    'fields' => 
    array (
      0 => 'type',
      1 => 'var',
      2 => 'desc',
    ),
  ),
  'return' => 
  array (
    0 => 'type',
    1 => 'desc',
  ),
  'var' => 
  array (
    'key' => 'var',
    'fields' => 
    array (
      0 => 'type',
      1 => 'var',
      2 => 'desc',
    ),
  ),
  'exception' => 
  array (
    0 => 'type',
    1 => 'desc',
  ),
)

Type: array

(such as @param type var desc and @return type desc) and the names of those parameters.

brief

public string $brief

Type: string

detail

public string $detail

Type: string

tags

The tags defined in the docblock.

private array $tags

Type: array

The array has keys which are the tag names (excluding the @) and values that are arrays, each of which is an entry for the tag.

In the case where the tag name is defined in Hazaar\Parser\DocBlock::vectors the value within the tag-value array is an array in itself with keys as described by Hazaar\Parser\DocBlock::vectors.

Methods

__construct

Creates a docblock parser and optionally parses an initial comment.

public __construct(null $comment): void

Parameters

Parameter	Type	Description
$comment	null	raw docblock text to parse immediately

setComment

Resets parser state and parses a new docblock comment.

public setComment(string $comment): void

Returns: void

Parameters

Parameter	Type	Description
$comment	string	docblock text including comment markers

hasTag

Checks whether the parsed docblock contains a given tag.

public hasTag(string $tag): bool

Returns: bool

Parameters

Parameter	Type	Description
$tag	string	tag name without the @ prefix

tag

Returns all entries for a tag.

public tag(string $tag): ?array

Returns: array

Parameters

Parameter	Type	Description
$tag	string	tag name without the @ prefix

tagImplode

Returns a tag's values concatenated as text.

public tagImplode(string $tag, string $sep = ' '): ?string

Returns: string

Parameters

Parameter	Type	Description
$tag	string	tag name without the @ prefix
$sep	string	separator inserted between values

tagMerge

Merges nested entries for a tag into a single array.

public tagMerge(string $tag): ?array

Returns: array

Parameters

Parameter	Type	Description
$tag	string	tag name without the @ prefix

toArray

Returns the parsed docblock as a serialisable array.

public toArray(): array

Returns: array

brief

Returns the brief description, when present.

public brief(): ?string

Returns: string

detail

Returns the detailed description, when present.

public detail(): ?string

Returns: string

setBrief

Overwrites the brief description.

public setBrief(?string $brief): void

Returns: void

Used by consumers (e.g. Documentor) that rewrite parsed text in place, such as resolving {@see} tags into rendered links.

Parameters

Parameter	Type	Description
$brief	string

setDetail

Overwrites the detailed description.

public setDetail(?string $detail): void

Returns: void

Used by consumers (e.g. Documentor) that rewrite parsed text in place, such as resolving {@see} tags into rendered links.

Parameters

Parameter	Type	Description
$detail	string

parseComment

Parses a docblock comment and populates the parser state.

protected parseComment(string $comment): void

Returns: void

This extracts description text and tagged sections, and transforms known vector tags (@param, @return, etc.) into keyed arrays.

Parameters

Parameter	Type	Description
$comment	string	raw docblock text

setDescription

Parses the non-tagged description block.

protected setDescription(string $body): void

Returns: void

The first line is treated as the brief description and remaining text, if any, becomes the detailed description.

Parameters

Parameter	Type	Description
$body	string	description block text

trimTextBlock

Normalises indentation and trims surrounding whitespace in text blocks.

private trimTextBlock(string $string): string

Returns: string

Parameters

Parameter	Type	Description
$string	string	raw multi-line text block

isTagged

Checks whether a string begins with a valid @tag marker.

private isTagged(string $str): bool

Returns: bool

Parameters

Parameter	Type	Description
$str	string

strTag

Returns the leading @tag token from a string.

private strTag(string $str): ?string

Returns: string

Parameters

Parameter	Type	Description
$str	string

---

Generated by Hazaar API Doc Generator on Fri, 04 Sep 2026 23:32:16 +0000