mirrors/barryvdh_ReflectionDocBlock
1
0
Fork 0
mirror of https://github.com/barryvdh/ReflectionDocBlock.git synced 2026-08-18 01:57:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'release/2.x' of https://github.com/phpDocumentor/ReflectionDocBlock

Browse Source
This commit is contained in:
Barry vd. Heuvel
2016-06-13 21:28:05 +02:00
parent fd9e6bd26d e6a969a640
commit d411a2bc7e
29 changed files with 802 additions and 239 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Barryvdh/Reflection/DocBlock.php
+118 -64
View File
@@ -46,6 +46,12 @@ class DocBlock implements \Reflector
/** @var Location Information about the location of this DocBlock. */
protected $location = null;
/** @var bool Is this DocBlock (the start of) a template? */
protected $isTemplateStart = false;
/** @var bool Does this DocBlock signify the end of a DocBlock template? */
protected $isTemplateEnd = false;
/**
* Parses the given docblock and populates the member fields.
*
@@ -81,7 +87,9 @@ class DocBlock implements \Reflector
$docblock = $this->cleanInput($docblock);
list($short, $long, $tags) = $this->splitDocBlock($docblock);
list($templateMarker, $short, $long, $tags) = $this->splitDocBlock($docblock);
$this->isTemplateStart = $templateMarker === '#@+';
$this->isTemplateEnd = $templateMarker === '#@-';
$this->short_description = $short;
$this->long_description = new DocBlock\Description($long, $this);
$this->parseTags($tags);
@@ -119,74 +127,86 @@ class DocBlock implements \Reflector
}
/**
* Splits the DocBlock into a short description, long description and
* block of tags.
* Splits the DocBlock into a template marker, summary, description and block of tags.
*
* @param string $comment Comment to split into the sub-parts.
*
* @author RichardJ Special thanks to RichardJ for the regex responsible
* for the split.
* @author Richard van Velzen (@_richardJ) Special thanks to Richard for the regex responsible for the split.
* @author Mike van Riel <[email protected]> for extending the regex with template marker support.
*
* @return string[] containing the short-, long description and an element
* containing the tags.
* @return string[] containing the template marker (if any), summary, description and a string containing the tags.
*/
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) {
$matches = array('', '', $comment);
} else {
// clears all extra horizontal whitespace from the line endings
// to prevent parsing issues
$comment = preg_replace('/\h*$/Sum', '', $comment);
/*
* Splits the docblock into a short description, long description and
* tags section
* - 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)
* - 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 (
[^\n.]+
(?:
(?! \. \n | \n{2} ) # disallow the first seperator here
[\n.] (?! [ \t]* @\pL ) # disallow second seperator
[^\n.]+
)*
\.?
)
(?:
\s* # first seperator (actually newlines but it\'s all whitespace)
(?! @\pL ) # disallow the rest, to make sure this one doesn\'t match,
#if it doesn\'t exist
(
[^\n]+
(?: \n+
(?! [ \t]* @\pL ) # disallow second seperator (@param)
[^\n]+
)*
)
)?
(\s+ [\s\S]*)? # everything that follows
/ux',
$comment,
$matches
);
array_shift($matches);
return array('', '', '', $comment);
}
while (count($matches) < 3) {
// 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;
}
@@ -209,20 +229,16 @@ class DocBlock implements \Reflector
);
}
foreach (explode("\n", $tags) as $tag_line) {
if (trim($tag_line) === '') {
continue;
}
if (isset($tag_line[0]) && ($tag_line[0] === '@')) {
$result[] = $tag_line;
} else {
$result[count($result) - 1] .= PHP_EOL . $tag_line;
$result[count($result) - 1] .= "\n" . $tag_line;
}
}
// create proper Tag objects
foreach ($result as $key => $tag_line) {
$result[$key] = Tag::createInstance($tag_line, $this);
$result[$key] = Tag::createInstance(trim($tag_line), $this);
}
}
@@ -261,7 +277,7 @@ class DocBlock implements \Reflector
*/
public function setText($comment)
{
list($short, $long) = $this->splitDocBlock($comment);
list(,$short, $long) = $this->splitDocBlock($comment);
$this->short_description = $short;
$this->long_description = new DocBlock\Description($long, $this);
return $this;
@@ -286,6 +302,44 @@ class DocBlock implements \Reflector
return $this->long_description;
}
/**
* 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 (`#@-`).
*
* @see self::isTemplateEnd() for the check whether a closing marker was provided.
*
* @return boolean
*/
public function isTemplateStart()
{
return $this->isTemplateStart;
}
/**
* Returns whether this DocBlock is the end of a Template section.
*
* @see self::isTemplateStart() for a more complete description of the Docblock Template functionality.
*
* @return boolean
*/
public function isTemplateEnd()
{
return $this->isTemplateEnd;
}
/**
* Returns the current context.
*
src/Barryvdh/Reflection/DocBlock/Description.php
+11 -8
View File
@@ -55,15 +55,15 @@ class Description implements \Reflector
/**
* Sets the text of this description.
*
*
* @param string $content The new text of this description.
*
*
* @return $this
*/
public function setContent($content)
{
$this->contents = trim($content);
$this->parsedContents = null;
return $this;
}
@@ -140,7 +140,7 @@ class Description implements \Reflector
*
* @todo this should become a more intelligent piece of code where the
* configuration contains a setting what format long descriptions are.
*
*
* @codeCoverageIgnore Will be removed soon, in favor of adapters at
* PhpDocumentor itself that will process text in various formats.
*
@@ -161,7 +161,10 @@ class Description implements \Reflector
);
}
if (class_exists('dflydev\markdown\MarkdownExtraParser')) {
if (class_exists('Parsedown')) {
$markdown = \Parsedown::instance();
$result = $markdown->parse($result);
} elseif (class_exists('dflydev\markdown\MarkdownExtraParser')) {
$markdown = new \dflydev\markdown\MarkdownExtraParser();
$result = $markdown->transformMarkdown($result);
}
@@ -171,7 +174,7 @@ class Description implements \Reflector
/**
* Gets the docblock this tag belongs to.
*
*
* @return DocBlock The docblock this description belongs to.
*/
public function getDocBlock()
@@ -181,10 +184,10 @@ class Description implements \Reflector
/**
* Sets the docblock this tag belongs to.
*
*
* @param DocBlock $docblock The new docblock this description belongs to.
* Setting NULL removes any association.
*
*
* @return $this
*/
public function setDocBlock(DocBlock $docblock = null)
src/Barryvdh/Reflection/DocBlock/Tag/ExampleTag.php
+1 -1
View File
@@ -56,7 +56,7 @@ class ExampleTag extends SourceTag
$filePath = '"' . $this->filePath . '"';
}
$this->content = $filePath . ' ' . $this->getContent();
$this->content = $filePath . ' ' . parent::getContent();
}
return $this->content;
src/Barryvdh/Reflection/DocBlock/Tag/MethodTag.php
-3
View File
@@ -114,9 +114,6 @@ class MethodTag extends ReturnTag
}
}
$this->parsedDescription = null;
} else {
echo date('c') . ' ERR (3): @method contained invalid contents: '
. $this->content . PHP_EOL;
}
return $this;
src/Barryvdh/Reflection/DocBlock/Tag/ParamTag.php
+21 -5
View File
@@ -23,11 +23,12 @@ use Barryvdh\Reflection\DocBlock\Tag;
*/
class ParamTag extends ReturnTag
{
/**
* @var string
*/
/** @var string */
protected $variableName = '';
/** @var bool determines whether this is a variadic argument */
protected $isVariadic = false;
/**
* {@inheritdoc}
*/
@@ -61,13 +62,18 @@ class ParamTag extends ReturnTag
array_shift($parts);
}
// if the next item starts with a $ it must be the variable name
// if the next item starts with a $ or ...$ it must be the variable name
if (isset($parts[0])
&& (strlen($parts[0]) > 0)
&& ($parts[0][0] == '$')
&& ($parts[0][0] == '$' || substr($parts[0], 0, 4) === '...$')
) {
$this->variableName = array_shift($parts);
array_shift($parts);
if (substr($this->variableName, 0, 3) === '...') {
$this->isVariadic = true;
$this->variableName = substr($this->variableName, 3);
}
}
$this->setDescription(implode('', $parts));
@@ -100,4 +106,14 @@ class ParamTag extends ReturnTag
$this->content = null;
return $this;
}
/**
* Returns whether this tag is variadic.
*
* @return boolean
*/
public function isVariadic()
{
return $this->isVariadic;
}
}
src/Barryvdh/Reflection/DocBlock/Type/Collection.php
+8 -1
View File
@@ -166,7 +166,8 @@ class Collection extends \ArrayObject
$namespace_aliases = $this->context->getNamespaceAliases();
// if the first segment is not an alias; prepend namespace name and
// return
if (!isset($namespace_aliases[$type_parts[0]])) {
if (!isset($namespace_aliases[$type_parts[0]]) &&
!isset($namespace_aliases[strstr($type_parts[0], '::', true)])) {
$namespace = $this->context->getNamespace();
if ('' !== $namespace) {
$namespace .= self::OPERATOR_NAMESPACE;
@@ -174,6 +175,12 @@ class Collection extends \ArrayObject
return self::OPERATOR_NAMESPACE . $namespace . $type;
}
if (strpos($type_parts[0], '::')) {
$type_parts[] = strstr($type_parts[0], '::');
$type_parts[0] = $namespace_aliases[strstr($type_parts[0], '::', true)];
return implode('', $type_parts);
}
$type_parts[0] = $namespace_aliases[$type_parts[0]];
$type = implode(self::OPERATOR_NAMESPACE, $type_parts);
}