1. class
  2. Alligator
  3. \
  4. Helpers
  5. \
  6. Parser
  7. \
  8. DocBlock

DocBlock

class DocBlock implements Reflector

Class DocBlock - Parses the DocBlock for any structure.

Properties

protected string $shortDescription
protected Description $longDescription
protected Tag[] $tags
protected Context $context
protected Location $location
protected bool $isTemplateStart
protected bool $isTemplateEnd

Methods

__construct(Reflector|string $docblock, Context $context = null, Location $location = null, bool $parseTags = false)

Parses the given docblock and populates the member fields.

string
getText()

Gets the text portion of the doc block.

DocBlock
setText(string $comment)

Set the text portion of the doc block.

string
getShortDescription()

Returns the opening line or also known as short description.

Description
getLongDescription()

Returns the full description or also known as long description.

boolean
isTemplateStart()

Returns whether this DocBlock is the start of a Template section.

boolean
isTemplateEnd()

Returns whether this DocBlock is the end of a Template section.

Context
getContext()

Returns the current context.

Location
getLocation()

Returns the current location.

Tag[]
getTags()

Returns the tags for this DocBlock.

Tag[]
getTagsByName(string $name)

Returns an array of tags matching the given name. If no tags are found an empty array is returned.

bool
hasTag(string $name)

Checks if a tag of a certain type is present in this DocBlock.

Tag
appendTag(Tag $tag)

Appends a tag at the end of the list of tags.

static string
export()

Builds a string representation of this object.

string
__toString()

Returns the exported information (we should use the export static method BUT this throws an exception at this point).

string
cleanInput(string $comment)

Strips the asterisks from the DocBlock comment.

string[]
splitDocBlock(string $comment)

Splits the DocBlock into a template marker, summary, description and block of tags.

void
parseTags(string $tags)

Creates the tag objects.

Details

at line 61
__construct(Reflector|string $docblock, Context $context = null, Location $location = null, bool $parseTags = false)

Parses the given docblock and populates the member fields.

The constructor may also receive namespace information such as the current namespace and aliases. This information is used by some tags (e.g. @return, @param, etc.) to turn a relative Type into a FQCN.

Parameters

Reflector|string $docblock A docblock comment (including asterisks) or reflector supporting the getDocComment method.
Context $context The context in which the DocBlock occurs.
Location $location The location within the file that this DocBlock occurs in.
bool $parseTags parse tag occurs in DocBlock.

Exceptions

InvalidArgumentException if the given argument does not have the getDocComment method.

at line 90
string getText()

Gets the text portion of the doc block.

Gets the text portion (short and long description combined) of the doc block.

Return Value

string The text portion of the doc block.

at line 111
DocBlock setText(string $comment)

Set the text portion of the doc block.

Sets the text portion (short and long description combined) of the doc block.

Parameters

string $comment The new text portion of the doc block.

Return Value

DocBlock This doc block.

at line 125
string getShortDescription()

Returns the opening line or also known as short description.

Return Value

string

at line 135
Description getLongDescription()

Returns the full description or also known as long description.

Return Value

Description

at line 161
boolean isTemplateStart()

Returns whether this DocBlock is the start of a Template section.

A Docblock may serve as template for a series of subsequent DocBlocks. This is indicated by a special marker (#@+) that is appended directly after the opening /** of a DocBlock.

An example of such an opening is:

/**#@+
 * My DocBlock
 * /

The description and tags (not the summary!) are copied onto all subsequent DocBlocks and also applied to all elements that follow until another DocBlock is found that contains the closing marker (#@-).

Return Value

boolean

See also

DocBlock::isTemplateEnd for the check whether a closing marker was provided.

at line 173
boolean isTemplateEnd()

Returns whether this DocBlock is the end of a Template section.

Return Value

boolean

See also

DocBlock::isTemplateStart for a more complete description of the Docblock Template functionality.

at line 183
Context getContext()

Returns the current context.

Return Value

Context

at line 193
Location getLocation()

Returns the current location.

Return Value

Location

at line 203
Tag[] getTags()

Returns the tags for this DocBlock.

Return Value

Tag[]

at line 216
Tag[] getTagsByName(string $name)

Returns an array of tags matching the given name. If no tags are found an empty array is returned.

Parameters

string $name String to search by.

Return Value

Tag[]

at line 237
bool hasTag(string $name)

Checks if a tag of a certain type is present in this DocBlock.

Parameters

string $name Tag name to check for.

Return Value

bool

at line 258
Tag appendTag(Tag $tag)

Appends a tag at the end of the list of tags.

Parameters

Tag $tag The tag to add.

Return Value

Tag The newly added tag.

Exceptions

LogicException When the tag belongs to a different DocBlock.

at line 285
static string export()

Builds a string representation of this object.

Return Value

string

Exceptions

Exception

at line 298
string __toString()

Returns the exported information (we should use the export static method BUT this throws an exception at this point).

Return Value

string

at line 310
protected string cleanInput(string $comment)

Strips the asterisks from the DocBlock comment.

Parameters

string $comment String containing the comment text.

Return Value

string

at line 339
protected string[] splitDocBlock(string $comment)

Splits the DocBlock into a template marker, summary, description and block of tags.

Parameters

string $comment Comment to split into the sub-parts.

Return Value

string[] containing the template marker (if any), summary, description and a string containing the tags.

at line 413
protected void parseTags(string $tags)

Creates the tag objects.

Parameters

string $tags Tag block to parse.

Return Value

void