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

Merge branch 'master' of github.com:boenrobot/ReflectionDocBlock into author

Browse Source 
Conflicts:
	src/phpDocumentor/Reflection/DocBlock/Tag/AuthorTag.php
This commit is contained in:
Vasil Rangelov
2012-11-13 19:13:34 +02:00
parent f19dac185a 1ac9106c48
commit c2f692140f
24 changed files with 862 additions and 431 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/phpDocumentor/Reflection/DocBlock.php
+9 -87
View File
@@ -39,7 +39,7 @@ class DocBlock implements \Reflector
/** @var string the current namespace */
protected $namespace = '\\';
/** @var string[] List of namespace aliases => Fully Qualified Namespace */
/** @var array List of namespace aliases => Fully Qualified Namespace */
protected $namespace_aliases = array();
/**
@@ -56,7 +56,7 @@ class DocBlock implements \Reflector
* asterisks) or reflector supporting the getDocComment method.
* @param string $namespace The namespace where this
* DocBlock resides in; defaults to `\`.
* @param string[] $namespace_aliases A list of namespace aliases
* @param array $namespace_aliases A list of namespace aliases
* as provided by the `use` keyword; the key of the array is the alias
* name or last part of the alias array if no alias name is provided.
*
@@ -66,7 +66,7 @@ class DocBlock implements \Reflector
public function __construct(
$docblock,
$namespace = '\\',
$namespace_aliases = array()
array $namespace_aliases = array()
) {
if (is_object($docblock)) {
if (!method_exists($docblock, 'getDocComment')) {
@@ -83,7 +83,7 @@ class DocBlock implements \Reflector
list($short, $long, $tags) = $this->splitDocBlock($docblock);
$this->short_description = $short;
$this->long_description = new DocBlock\LongDescription($long);
$this->long_description = new DocBlock\Description($long);
$this->parseTags($tags);
$this->namespace = $namespace;
@@ -222,9 +222,7 @@ class DocBlock implements \Reflector
// create proper Tag objects
foreach ($result as $key => $tag_line) {
$tag = DocBlock\Tag::createInstance($tag_line);
$tag->setDocBlock($this);
$result[$key] = $tag;
$result[$key] = DocBlock\Tag::createInstance($tag_line, $this);
}
}
@@ -304,85 +302,6 @@ class DocBlock implements \Reflector
return false;
}
/**
* Tries to expand a type to it's full namespaced equivalent (FQCN).
*
* This method will take the given type and examine the current namespace
* and namespace aliases to see whether it should expand it into a FQCN
* as defined by the rules in PHP.
*
* @param string $type Type to expand into full namespaced
* equivalent.
* @param string[] $ignore_keywords Whether to ignore given keywords, when
* null it will use the default keywords:
* 'string', 'int', 'integer', 'bool', 'boolean', 'float', 'double',
* 'object', 'mixed', 'array', 'resource', 'void', 'null', 'callback',
* 'false', 'true', 'self', '$this', 'callable'.
* Default value for this parameter is null.
*
* @return string
*/
public function expandType($type, $ignore_keywords = null)
{
if ($type === null) {
return null;
}
if ($ignore_keywords === null) {
$ignore_keywords = array(
'string', 'int', 'integer', 'bool', 'boolean', 'float',
'double', 'object', 'mixed', 'array', 'resource', 'void',
'null', 'callback', 'false', 'true', 'self', '$this', 'callable'
);
}
$namespace = '\\';
if ($this->namespace != 'default' && $this->namespace != 'global') {
$namespace = rtrim($this->namespace, '\\') . '\\';
}
$type = explode('|', $type);
foreach ($type as &$item) {
$item = trim($item);
// add support for array notation
$is_array = false;
if (substr($item, -2) == '[]') {
$item = substr($item, 0, -2);
$is_array = true;
}
if ((substr($item, 0, 1) != '\\')
&& (!in_array(strtolower($item), $ignore_keywords))
) {
$type_parts = explode('\\', $item);
// if the first segment is an alias; replace with full name
if (isset($this->namespace_aliases[$type_parts[0]])) {
$type_parts[0] = $this->namespace_aliases[$type_parts[0]];
$item = implode('\\', $type_parts);
} else {
// otherwise prepend the current namespace
$item = $namespace . $item;
}
}
// full paths always start with a slash
if (isset($item[0]) && ($item[0] !== '\\')
&& (!in_array(strtolower($item), $ignore_keywords))
) {
$item = '\\' . $item;
}
// re-add the array notation markers
if ($is_array) {
$item .= '[]';
}
}
return implode('|', $type);
}
/**
* Builds a string representation of this object.
*
@@ -410,13 +329,16 @@ class DocBlock implements \Reflector
}
/**
* @return string
* @return string The namespace where this DocBlock resides in.
*/
public function getNamespace()
{
return $this->namespace;
}
/**
* @return array List of namespace aliases => Fully Qualified Namespace.
*/
public function getNamespaceAliases()
{
return $this->namespace_aliases;
src/phpDocumentor/Reflection/DocBlock/LongDescription.php → src/phpDocumentor/Reflection/DocBlock/Description.php
+14 -5
View File
@@ -13,13 +13,13 @@
namespace phpDocumentor\Reflection\DocBlock;
/**
* Parses a Long Description of a DocBlock.
* Parses a Description of a DocBlock or tag.
*
* @author Mike van Riel <mike.vanriel@naenius.com>
* @license http://www.opensource.org/licenses/mit-license.php MIT
* @link http://phpdoc.org
*/
class LongDescription implements \Reflector
class Description implements \Reflector
{
/** @var string */
protected $contents = '';
@@ -30,15 +30,20 @@ class LongDescription implements \Reflector
/** @var \phpDocumentor\Reflection\DocBlock\Tags[] */
protected $tags = array();
/** @var DocBlock The DocBlock which this description belongs to. */
protected $docblock = null;
/**
* Parses the string for inline tags and if the Markdown class is included;
* format the found text.
*
* @param string $content the DocBlock contents without asterisks.
* @param string $content The DocBlock contents without asterisks.
* @param DocBlock $docblock The DocBlock which this description belongs to.
*/
public function __construct($content)
public function __construct($content, DocBlock $docblock = null)
{
$this->contents = trim($content);
$this->docblock = $docblock;
}
/**
@@ -97,7 +102,8 @@ class LongDescription implements \Reflector
);
for ($i=1, $l = count($this->parsedContents); $i<$l; $i += 2) {
$this->parsedContents[$i] = Tag::createInstance(
$this->parsedContents[$i]
$this->parsedContents[$i],
$this->docblock
);
}
@@ -120,6 +126,9 @@ class LongDescription 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.
*
* @return string
*/
src/phpDocumentor/Reflection/DocBlock/Tag.php
+98 -36
View File
@@ -12,6 +12,8 @@
namespace phpDocumentor\Reflection\DocBlock;
use phpDocumentor\Reflection\DocBlock;
/**
* Parses a tag definition for a DocBlock.
*
@@ -36,20 +38,59 @@ class Tag implements \Reflector
/** @var int Line number of the tag */
protected $line_number = 0;
/** @var \phpDocumentor\Reflection\DocBlock docblock class */
protected $docblock;
/** @var DocBlock The DocBlock which this tag belongs to. */
protected $docblock = null;
/**
* @var array An array with a tag as a key, and an FQCN to a class that
* handles it as an array value. The class is expected to inherit this
* class.
*/
private static $tagHandlerMappings = array(
'author'
=> '\phpDocumentor\Reflection\DocBlock\Tag\AuthorTag',
'covers'
=> '\phpDocumentor\Reflection\DocBlock\Tag\CoversTag',
'link'
=> '\phpDocumentor\Reflection\DocBlock\Tag\LinkTag',
'method'
=> '\phpDocumentor\Reflection\DocBlock\Tag\MethodTag',
'param'
=> '\phpDocumentor\Reflection\DocBlock\Tag\ParamTag',
'property-read'
=> '\phpDocumentor\Reflection\DocBlock\Tag\PropertyReadTag',
'property'
=> '\phpDocumentor\Reflection\DocBlock\Tag\PropertyTag',
'property-write'
=> '\phpDocumentor\Reflection\DocBlock\Tag\PropertyWriteTag',
'return'
=> '\phpDocumentor\Reflection\DocBlock\Tag\ReturnTag',
'see'
=> '\phpDocumentor\Reflection\DocBlock\Tag\SeeTag',
'throw'
=> '\phpDocumentor\Reflection\DocBlock\Tag\ThrowsTag',
'throws'
=> '\phpDocumentor\Reflection\DocBlock\Tag\ThrowsTag',
'uses'
=> '\phpDocumentor\Reflection\DocBlock\Tag\UsesTag',
'var'
=> '\phpDocumentor\Reflection\DocBlock\Tag\VarTag'
);
/**
* Factory method responsible for instantiating the correct sub type.
*
* @param string $tag_line The text for this tag, including description.
* @param string $tag_line The text for this tag, including description.
* @param DocBlock $docblock The DocBlock which this tag belongs to.
*
* @throws \InvalidArgumentException if an invalid tag line was presented.
*
* @return \phpDocumentor\Reflection\DocBlock\Tag
* @return static A new tag object.
*/
public static function createInstance($tag_line)
{
final public static function createInstance(
$tag_line,
DocBlock $docblock = null
) {
if (!preg_match(
'/^@([\w\-\_\\\\]+)(?:\s*([^\s].*)|$)?/us',
$tag_line,
@@ -60,31 +101,66 @@ class Tag implements \Reflector
);
}
// support hypphen separated tag names
$tag_name = str_replace(
' ',
'',
ucwords(str_replace('-', ' ', $matches[1]))
).'Tag';
$class_name = 'phpDocumentor\\Reflection\\DocBlock\\Tag\\' . $tag_name;
if (isset(self::$tagHandlerMappings[$matches[1]])) {
$handler = self::$tagHandlerMappings[$matches[1]];
return new $handler(
$matches[1],
isset($matches[2]) ? $matches[2] : '',
$docblock
);
}
return new self(
$matches[1],
isset($matches[2]) ? $matches[2] : '',
$docblock
);
}
return ($matches[1] === strtolower($matches[1])
&& @class_exists($class_name))
? new $class_name($matches[1], isset($matches[2]) ? $matches[2] : '')
: new self($matches[1], isset($matches[2]) ? $matches[2] : '');
/**
* Registers a handler for tags.
*
* Registers a handler for tags. The class specified is autoloaded if it's
* not available. It must inherit from this class.
*
* @param string $tag Name of tag to regiser a handler for.
* @param string|null $handler FQCN of handler. Specifing NULL removes the
* handler for the specified tag, if any.
*
* @return bool TRUE on success, FALSE on failure.
*/
final public static function registerTagHandler($tag, $handler)
{
$tag = trim((string)$tag);
if (null === $handler) {
unset(self::$tagHandlerMappings[$tag]);
return true;
}
if ('' !== $tag
&& class_exists($handler, true)
&& is_subclass_of($handler, __CLASS__)
) {
self::$tagHandlerMappings[$tag] = $handler;
return true;
}
return false;
}
/**
* Parses a tag and populates the member variables.
*
* @param string $type Name of the tag.
* @param string $content The contents of the given tag.
* @param string $type Name of the tag.
* @param string $content The contents of the given tag.
* @param DocBlock $docblock The DocBlock which this tag belongs to.
*/
public function __construct($type, $content)
public function __construct($type, $content, DocBlock $docblock = null)
{
$this->tag = $type;
$this->content = $content;
$this->description = $content;
$this->description = trim($content);
$this->docblock = $docblock;
}
/**
@@ -126,7 +202,7 @@ class Tag implements \Reflector
public function getParsedDescription()
{
if (null === $this->parsedDescription) {
$description = new LongDescription($this->description);
$description = new Description($this->description, $this->docblock);
$this->parsedDescription = $description->getParsedContents();
}
return $this->parsedDescription;
@@ -154,20 +230,6 @@ class Tag implements \Reflector
return $this->line_number;
}
/**
* Inject the docblock class
*
* This exposes some common functionality contained in the docblock abstract.
*
* @param object $docblock Object containing the DocBlock.
*
* @return void
*/
public function setDocBlock($docblock)
{
$this->docblock = $docblock;
}
/**
* Builds a string representation of this object.
*
src/phpDocumentor/Reflection/DocBlock/Tag/AuthorTag.php
+5 -3
View File
@@ -12,6 +12,7 @@
namespace phpDocumentor\Reflection\DocBlock\Tag;
use phpDocumentor\Reflection\DocBlock;
use phpDocumentor\Reflection\DocBlock\Tag;
/**
@@ -35,10 +36,11 @@ class AuthorTag extends Tag
/**
* Parses a tag and populates the member variables.
*
* @param string $type Tag identifier for this tag (should be 'author').
* @param string $content The contents of the given tag.
* @param string $type Tag identifier for this tag (should be 'author').
* @param string $content Contents for this tag.
* @param DocBlock $docblock The DocBlock which this tag belongs to.
*/
public function __construct($type, $content)
public function __construct($type, $content, DocBlock $docblock = null)
{
$this->tag = $type;
$this->content = $content;
src/phpDocumentor/Reflection/DocBlock/Tag/LinkTag.php
+7 -5
View File
@@ -12,6 +12,7 @@
namespace phpDocumentor\Reflection\DocBlock\Tag;
use phpDocumentor\Reflection\DocBlock;
use phpDocumentor\Reflection\DocBlock\Tag;
/**
@@ -29,13 +30,14 @@ class LinkTag extends Tag
/**
* Parses a tag and populates the member variables.
*
* @param string $type Tag identifier for this tag (should be 'link').
* @param string $content The contents of the given tag.
* @param string $type Tag identifier for this tag (should be 'link').
* @param string $content Contents for this tag.
* @param DocBlock $docblock The DocBlock which this tag belongs to.
*/
public function __construct($type, $content)
public function __construct($type, $content, DocBlock $docblock = null)
{
$this->tag = $type;
$pieces = explode(' ', $content);
parent::__construct($type, $content, $docblock);
$pieces = explode(' ', $this->description);
if (count($pieces) > 1) {
$this->link = array_shift($pieces);
src/phpDocumentor/Reflection/DocBlock/Tag/MethodTag.php
+10 -7
View File
@@ -12,6 +12,9 @@
namespace phpDocumentor\Reflection\DocBlock\Tag;
use phpDocumentor\Reflection\DocBlock;
use phpDocumentor\Reflection\DocBlock\Tag;
/**
* Reflection class for a @method in a Docblock.
*
@@ -19,7 +22,7 @@ namespace phpDocumentor\Reflection\DocBlock\Tag;
* @license http://www.opensource.org/licenses/mit-license.php MIT
* @link http://phpdoc.org
*/
class MethodTag extends ParamTag
class MethodTag extends ReturnTag
{
/** @var string */
@@ -31,13 +34,13 @@ class MethodTag extends ParamTag
/**
* Parses a tag and populates the member variables.
*
* @param string $type Tag identifier for this tag (should be 'method').
* @param string $content The contents of the given tag.
* @param string $type Tag identifier for this tag (should be 'method').
* @param string $content Contents for this tag.
* @param DocBlock $docblock The DocBlock which this tag belongs to.
*/
public function __construct($type, $content)
public function __construct($type, $content, DocBlock $docblock = null)
{
$this->tag = $type;
$this->content = $content;
Tag::__construct($type, $content, $docblock);
$matches = array();
// 1. none or more whitespace
@@ -51,7 +54,7 @@ class MethodTag extends ParamTag
if (preg_match(
'/^[\s]*(?:([\w\|_\\\\]+)[\s]+)?(?:[\w_]+\(\)[\s]+)?([\w\|_\\\\]+)'
.'\(([^\)]*)\)[\s]*(.*)/u',
$content,
$this->description,
$matches
)) {
list(
src/phpDocumentor/Reflection/DocBlock/Tag/ParamTag.php
+16 -37
View File
@@ -12,6 +12,7 @@
namespace phpDocumentor\Reflection\DocBlock\Tag;
use phpDocumentor\Reflection\DocBlock;
use phpDocumentor\Reflection\DocBlock\Tag;
/**
@@ -21,11 +22,8 @@ use phpDocumentor\Reflection\DocBlock\Tag;
* @license http://www.opensource.org/licenses/mit-license.php MIT
* @link http://phpdoc.org
*/
class ParamTag extends Tag
class ParamTag extends ReturnTag
{
/** @var string */
protected $type = '';
/**
* @var string
*/
@@ -34,14 +32,19 @@ class ParamTag extends Tag
/**
* Parses a tag and populates the member variables.
*
* @param string $type Tag identifier for this tag (should be 'param').
* @param string $content Contents for this tag.
* @param string $type Tag identifier for this tag (should be 'param').
* @param string $content Contents for this tag.
* @param DocBlock $docblock The DocBlock which this tag belongs to.
*/
public function __construct($type, $content)
public function __construct($type, $content, DocBlock $docblock = null)
{
$this->tag = $type;
$this->content = $content;
$content = preg_split('/\s+/u', $content);
Tag::__construct($type, $content, $docblock);
$content = preg_split(
'/(\s+)/u',
$this->description,
3,
PREG_SPLIT_DELIM_CAPTURE
);
// if the first item that is encountered is not a variable; it is a type
if (isset($content[0])
@@ -49,6 +52,7 @@ class ParamTag extends Tag
&& ($content[0][0] !== '$')
) {
$this->type = array_shift($content);
array_shift($content);
}
// if the next item starts with a $ it must be the variable name
@@ -57,35 +61,10 @@ class ParamTag extends Tag
&& ($content[0][0] == '$')
) {
$this->variableName = array_shift($content);
array_shift($content);
}
$this->description = implode(' ', $content);
}
/**
* Returns the unique types of the variable.
*
* @return string[]
*/
public function getTypes()
{
$types = new \phpDocumentor\Reflection\DocBlock\Type\Collection(
array($this->type),
$this->docblock ? $this->docblock->getNamespace() : null,
$this->docblock ? $this->docblock->getNamespaceAliases() : array()
);
return $types->getArrayCopy();
}
/**
* Returns the type section of the variable.
*
* @return string
*/
public function getType()
{
return implode('|', $this->getTypes());
$this->description = implode('', $content);
}
/**
src/phpDocumentor/Reflection/DocBlock/Tag/ReturnTag.php
+37 -9
View File
@@ -12,6 +12,9 @@
namespace phpDocumentor\Reflection\DocBlock\Tag;
use phpDocumentor\Reflection\DocBlock;
use phpDocumentor\Reflection\DocBlock\Tag;
/**
* Reflection class for a @return tag in a Docblock.
*
@@ -19,27 +22,52 @@ namespace phpDocumentor\Reflection\DocBlock\Tag;
* @license http://www.opensource.org/licenses/mit-license.php MIT
* @link http://phpdoc.org
*/
class ReturnTag extends ParamTag
class ReturnTag extends Tag
{
/** @var string */
protected $type = null;
protected $type = '';
/**
* Parses a tag and populates the member variables.
*
* @param string $type Tag identifier for this tag (should be 'return').
* @param string $content Contents for this tag.
* @param string $type Tag identifier for this tag (should be 'return').
* @param string $content Contents for this tag.
* @param DocBlock $docblock The DocBlock which this tag belongs to.
*/
public function __construct($type, $content)
public function __construct($type, $content, DocBlock $docblock = null)
{
$this->tag = $type;
$this->content = $content;
$content = preg_split('/[\ \t]+/u', $content, 2);
parent::__construct($type, $content, $docblock);
$content = preg_split('/[\ \t]+/u', $this->description, 2);
// any output is considered a type
$this->type = array_shift($content);
$this->description = implode(' ', $content);
}
/**
* Returns the unique types of the variable.
*
* @return string[]
*/
public function getTypes()
{
$types = new \phpDocumentor\Reflection\DocBlock\Type\Collection(
array($this->type),
$this->docblock ? $this->docblock->getNamespace() : null,
$this->docblock ? $this->docblock->getNamespaceAliases() : array()
);
return $types->getArrayCopy();
}
/**
* Returns the type section of the variable.
*
* @return string
*/
public function getType()
{
return implode('|', $this->getTypes());
}
}
src/phpDocumentor/Reflection/DocBlock/Tag/SeeTag.php
+6 -5
View File
@@ -12,6 +12,7 @@
namespace phpDocumentor\Reflection\DocBlock\Tag;
use phpDocumentor\Reflection\DocBlock;
use phpDocumentor\Reflection\DocBlock\Tag;
/**
@@ -29,13 +30,13 @@ class SeeTag extends Tag
/**
* Parses a tag and populates the member variables.
*
* @param string $type Tag identifier for this tag (should be 'see').
* @param string $content Contents for this tag.
* @param string $type Tag identifier for this tag (should be 'see').
* @param string $content Contents for this tag.
* @param DocBlock $docblock The DocBlock which this tag belongs to.
*/
public function __construct($type, $content)
public function __construct($type, $content, DocBlock $docblock = null)
{
$this->tag = $type;
$this->content = $content;
parent::__construct($type, $content, $docblock);
$content = preg_split('/\s+/u', $content);
// any output is considered a type
src/phpDocumentor/Reflection/DocBlock/Tag/ThrowTag.php
-43
View File
@@ -1,43 +0,0 @@
<?php
/**
* phpDocumentor
*
* PHP Version 5.3
*
* @author Mike van Riel <[email protected]>
* @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com)
* @license http://www.opensource.org/licenses/mit-license.php MIT
* @link http://phpdoc.org
*/
namespace phpDocumentor\Reflection\DocBlock\Tag;
/**
* Reflection class for a mistyped @throws tag called @throw in a Docblock.
*
* This is a very common error, so @throw is aliased to be @throws
*
* @author Mike van Riel <[email protected]>
* @license http://www.opensource.org/licenses/mit-license.php MIT
* @link http://phpdoc.org
*/
class ThrowTag extends ThrowsTag
{
/**
* Sets the type to @throws and lets parent parse the tag and populates the
* member variables.
*
* @param string $type Tag identifier for this tag (should be 'throw').
* @param string $content Contents for this tag.
*/
public function __construct($type, $content)
{
if ('throw' !== $type) {
throw new \InvalidArgumentException(
'Internal error, ' . __CLASS__ . ' was called with ' . $type
);
}
parent::__construct('throws', $content);
}
}
src/phpDocumentor/Reflection/DocBlock/Tag/VarTag.php
+9 -6
View File
@@ -12,6 +12,9 @@
namespace phpDocumentor\Reflection\DocBlock\Tag;
use phpDocumentor\Reflection\DocBlock;
use phpDocumentor\Reflection\DocBlock\Tag;
/**
* Reflection class for a @var tag in a Docblock.
*
@@ -24,14 +27,14 @@ class VarTag extends ParamTag
/**
* Parses a tag and populates the member variables.
*
* @param string $type Tag identifier for this tag (should be 'var').
* @param string $content Contents for this tag.
* @param string $type Tag identifier for this tag (should be 'var').
* @param string $content Contents for this tag.
* @param DocBlock $docblock The DocBlock which this tag belongs to.
*/
public function __construct($type, $content)
public function __construct($type, $content, DocBlock $docblock = null)
{
$this->tag = $type;
$this->content = $content;
$content = preg_split('/\s+/u', $content);
Tag::__construct($type, $content, $docblock);
$content = preg_split('/\s+/u', $this->description);
if (count($content) == 0) {
return;