function DocBlockFactory::splitDocBlock

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

@author Mike van Riel <me@mikevanriel.com> for extending the regex with template marker support.

@author Richard van Velzen (@_richardJ) Special thanks to Richard for the regex responsible for the split.

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.

1 call to DocBlockFactory::splitDocBlock()

DocBlockFactory::create in vendor/phpdocumentor/reflection-docblock/src/DocBlockFactory.php

File

vendor/phpdocumentor/reflection-docblock/src/DocBlockFactory.php, line 193

Class

DocBlockFactory

Namespace

phpDocumentor\Reflection

Code

private function splitDocBlock(string $comment) : array {
    // phpcs:enable
    // 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 [
            '',
            '',
            '',
            $comment,
        ];
    }
    // clears all extra horizontal whitespace from the line endings to prevent parsing issues
    $comment = preg_replace('/\\h*$/Sum', '', $comment);
    Assert::string($comment);
    
    /*
     * Splits the docblock into a template marker, summary, 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;
}