protected function DocBlock::splitDocBlock in Zircon Profile 8

Same name and namespace in other branches

1. 8.0 vendor/phpdocumentor/reflection-docblock/src/phpDocumentor/Reflection/DocBlock.php \phpDocumentor\Reflection\DocBlock::splitDocBlock()

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

@author Richard van Velzen (@_richardJ) Special thanks to Richard for the regex responsible for the split. @author Mike van Riel <me@mikevanriel.com> for extending the regex with template marker support.

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.

2 calls to DocBlock::splitDocBlock()

DocBlock::setText in vendor/phpdocumentor/reflection-docblock/src/phpDocumentor/Reflection/DocBlock.php

Set the text portion of the doc block.

DocBlock::__construct in vendor/phpdocumentor/reflection-docblock/src/phpDocumentor/Reflection/DocBlock.php

Parses the given docblock and populates the member fields.

File

vendor/phpdocumentor/reflection-docblock/src/phpDocumentor/Reflection/DocBlock.php, line 139

Class

DocBlock

Parses the DocBlock for any structure.

Namespace

phpDocumentor\Reflection

Code

protected function splitDocBlock($comment) {

  // Performance improvement cheat: if the first character is an @ then only tags are in this DocBlock. This
  // method does not split tags so we return this verbatim as the fourth result (tags). This saves us the
  // performance impact of running a regular expression
  if (strpos($comment, '@') === 0) {
    return array(
      '',
      '',
      '',
      $comment,
    );
  }

  // clears all extra horizontal whitespace from the line endings to prevent parsing issues
  $comment = preg_replace('/\\h*$/Sum', '', $comment);

  /*
   * Splits the docblock into a template marker, short description, long description and tags section
   *
   * - The template marker is empty, #@+ or #@- if the DocBlock starts with either of those (a newline may
   *   occur after it and will be stripped).
   * - The short description is started from the first character until a dot is encountered followed by a
   *   newline OR two consecutive newlines (horizontal whitespace is taken into account to consider spacing
   *   errors). This is optional.
   * - The long description, any character until a new line is encountered followed by an @ and word
   *   characters (a tag). This is optional.
   * - Tags; the remaining characters
   *
   * Big thanks to RichardJ for contributing this Regular Expression
   */
  preg_match('/
            \\A
            # 1. Extract the template marker
            (?:(\\#\\@\\+|\\#\\@\\-)\\n?)?

            # 2. Extract the summary
            (?:
              (?! @\\pL ) # The summary may not start with an @
              (
                [^\\n.]+
                (?:
                  (?! \\. \\n | \\n{2} )     # End summary upon a dot followed by newline or two newlines
                  [\\n.] (?! [ \\t]* @\\pL ) # End summary when an @ is found as first character on a new line
                  [^\\n.]+                 # Include anything else
                )*
                \\.?
              )?
            )

            # 3. Extract the description
            (?:
              \\s*        # Some form of whitespace _must_ precede a description because a summary must be there
              (?! @\\pL ) # The description may not start with an @
              (
                [^\\n]+
                (?: \\n+
                  (?! [ \\t]* @\\pL ) # End description when an @ is found as first character on a new line
                  [^\\n]+            # Include anything else
                )*
              )
            )?

            # 4. Extract the tags (anything that follows)
            (\\s+ [\\s\\S]*)? # everything that follows
            /ux', $comment, $matches);
  array_shift($matches);
  while (count($matches) < 4) {
    $matches[] = '';
  }
  return $matches;
}