Documentation

DescriptionFactory
in package

Creates a new Description object given a body of text.

Descriptions in phpDocumentor are somewhat complex entities as they can contain one or more tags inside their body that can be replaced with a readable output. The replacing is done by passing a Formatter object to the Description object's render method.

In addition to the above does a Description support two types of escape sequences:

  1. @ to escape the @ character to prevent it from being interpreted as part of a tag, i.e. {@link}
  2. } to escape the } character, this can be used if you want to use the } character in the description of an inline tag.

If a body consists of multiple lines then this factory will also remove any superfluous whitespace at the beginning of each line while maintaining any indentation that is used. This will prevent formatting parsers from tripping over unexpected spaces as can be observed with tag descriptions.

Table of Contents

$tagFactory  : TagFactory
__construct()  : mixed
Initializes this factory with the means to construct (inline) tags.
create()  : Description
Returns the parsed text of this description.
lex()  : array<string|int, string>
Strips the contents from superfluous whitespace and splits the description into a series of tokens.
removeSuperfluousStartingWhitespace()  : string
Removes the superfluous from a multi-line description.

Properties

Methods

__construct()

Initializes this factory with the means to construct (inline) tags.

public __construct(TagFactory $tagFactory) : mixed
Parameters
$tagFactory : TagFactory
Return values
mixed

lex()

Strips the contents from superfluous whitespace and splits the description into a series of tokens.

private lex(string $contents) : array<string|int, string>
Parameters
$contents : string
Return values
array<string|int, string>

A series of tokens of which the description text is composed.

removeSuperfluousStartingWhitespace()

Removes the superfluous from a multi-line description.

private removeSuperfluousStartingWhitespace(string $contents) : string

When a description has more than one line then it can happen that the second and subsequent lines have an additional indentation. This is commonly in use with tags like this:

@since 1.1.0 This is an example
    description where we have an
    indentation in the second and
    subsequent lines.

If we do not normalize the indentation then we have superfluous whitespace on the second and subsequent lines and this may cause rendering issues when, for example, using a Markdown converter.

Parameters
$contents : string
Return values
string

Search results