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

Conflicts:
	src/phpDocumentor/Reflection/DocBlock/Tag/AuthorTag.php

src/phpDocumentor/Reflection/DocBlock.php

@@ -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);
+                $result[$key] = DocBlock\Tag::createInstance($tag_line, $this);
-                $tag->setDocBlock($this);
-                $result[$key] = $tag;
             }
         }
 
@@ -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/Description.php

@@ -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

@@ -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 */
+    /** @var DocBlock The DocBlock which this tag belongs to. */
-    protected $docblock;
+    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
+        if (isset(self::$tagHandlerMappings[$matches[1]])) {
-        $tag_name = str_replace(
+            $handler = self::$tagHandlerMappings[$matches[1]];
-            ' ',
+            return new $handler(
-            '',
+                $matches[1],
-            ucwords(str_replace('-', ' ', $matches[1]))
+                isset($matches[2]) ? $matches[2] : '',
-        ).'Tag';
+                $docblock
-        $class_name = 'phpDocumentor\\Reflection\\DocBlock\\Tag\\' . $tag_name;
+            );
+        }
+        return new self(
+            $matches[1],
+            isset($matches[2]) ? $matches[2] : '',
+            $docblock
+        );
+    }
 
-        return ($matches[1] === strtolower($matches[1])
+    /**
-            && @class_exists($class_name))
+     * Registers a handler for tags.
-            ? new $class_name($matches[1], isset($matches[2]) ? $matches[2] : '')
+     * 
-            : new self($matches[1], isset($matches[2]) ? $matches[2] : '');
+     * 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   $type     Name of the tag.
-     * @param string $content The contents of the given 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

@@ -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   $type     Tag identifier for this tag (should be 'author').
-     * @param string $content The contents of the given tag.
+     * @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

@@ -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   $type     Tag identifier for this tag (should be 'link').
-     * @param string $content The contents of the given tag.
+     * @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;
+        parent::__construct($type, $content, $docblock);
-        $pieces = explode(' ', $content);
+        $pieces = explode(' ', $this->description);
 
         if (count($pieces) > 1) {
             $this->link = array_shift($pieces);

src/phpDocumentor/Reflection/DocBlock/Tag/MethodTag.php

@@ -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   $type     Tag identifier for this tag (should be 'method').
-     * @param string $content The contents of the given tag.
+     * @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;
+        Tag::__construct($type, $content, $docblock);
-        $this->content = $content;
 
         $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

@@ -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   $type     Tag identifier for this tag (should be 'param').
-     * @param string $content Contents for this tag.
+     * @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;
+        Tag::__construct($type, $content, $docblock);
-        $this->content = $content;
+        $content = preg_split(
-        $content = preg_split('/\s+/u', $content);
+            '/(\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);
+        $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/ReturnTag.php

@@ -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   $type     Tag identifier for this tag (should be 'return').
-     * @param string $content Contents for this tag.
+     * @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;
+        parent::__construct($type, $content, $docblock);
-        $this->content = $content;
+        $content = preg_split('/[\ \t]+/u', $this->description, 2);
-
-        $content = preg_split('/[\ \t]+/u', $content, 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

@@ -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   $type     Tag identifier for this tag (should be 'see').
-     * @param string $content Contents for this tag.
+     * @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;
+        parent::__construct($type, $content, $docblock);
-        $this->content = $content;
         $content = preg_split('/\s+/u', $content);
 
         // any output is considered a type

src/phpDocumentor/Reflection/DocBlock/Tag/ThrowTag.php

@@ -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

@@ -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   $type     Tag identifier for this tag (should be 'var').
-     * @param string $content Contents for this tag.
+     * @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;
+        Tag::__construct($type, $content, $docblock);
-        $this->content = $content;
+        $content = preg_split('/\s+/u', $this->description);
-        $content = preg_split('/\s+/u', $content);
 
         if (count($content) == 0) {
             return;

tests/phpDocumentor/Reflection/DocBlock/DescriptionTest.php

@@ -1,6 +1,6 @@
 <?php
 /**
- * phpDocumentor Long Description Test
+ * phpDocumentor Description Test
  *
  * PHP Version 5.3
  *
@@ -13,21 +13,21 @@
 namespace phpDocumentor\Reflection\DocBlock;
 
 /**
- * Test class for phpDocumentor\Reflection\DocBlock\LongDescription
+ * Test class for phpDocumentor\Reflection\DocBlock\Description
  *
  * @author    Vasil Rangelov <boen.robot@gmail.com>
  * @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
  */
-class LongDescriptionTest extends \PHPUnit_Framework_TestCase
+class DescriptionTest extends \PHPUnit_Framework_TestCase
 {
     public function testConstruct()
     {
         $fixture = <<<LONGDESC
 This is text for a description.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->assertSame($fixture, $object->getContents());
 
         $parsedContents = $object->getParsedContents();
@@ -41,7 +41,7 @@ LONGDESC;
 This is text for a {@link http://phpdoc.org/ description} that uses inline
 tags.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->assertSame($fixture, $object->getContents());
 
         $parsedContents = $object->getParsedContents();
@@ -64,7 +64,7 @@ tags.',
 {@link http://phpdoc.org/ This} is text for a description that uses inline
 tags.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->assertSame($fixture, $object->getContents());
 
         $parsedContents = $object->getParsedContents();
@@ -88,7 +88,7 @@ tags.',
 This is text for a description with {@internal inline tag with
 {@link http://phpdoc.org another inline tag} in it}.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->assertSame($fixture, $object->getContents());
 
         $parsedContents = $object->getParsedContents();
@@ -119,7 +119,7 @@ LONGDESC;
         $fixture = <<<LONGDESC
 This is text for a description containing { that is literal.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->assertSame($fixture, $object->getContents());
 
         $parsedContents = $object->getParsedContents();
@@ -133,7 +133,7 @@ LONGDESC;
 This is text for a description containing {@internal inline tag that has { that
 is literal}.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->assertSame($fixture, $object->getContents());
 
         $parsedContents = $object->getParsedContents();
@@ -160,7 +160,7 @@ is literal'),
         $fixture = <<<LONGDESC
 This is text for a description with {} that is not a tag.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->assertSame($fixture, $object->getContents());
 
         $parsedContents = $object->getParsedContents();
@@ -177,7 +177,7 @@ LONGDESC;
 This is text for a description with {@internal inline tag with {} that is not an
 inline tag}.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->assertSame($fixture, $object->getContents());
 
         $parsedContents = $object->getParsedContents();
@@ -204,7 +204,7 @@ inline tag'),
         $fixture = <<<LONGDESC
 This is text for a description with literal {{@}link}.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->assertSame($fixture, $object->getContents());
 
         $parsedContents = $object->getParsedContents();
@@ -221,7 +221,7 @@ LONGDESC;
 This is text for a description with an {@internal inline tag with literal
 {{@}link{} in it}.
 LONGDESC;
-        $object = new LongDescription($fixture);
+        $object = new Description($fixture);
         $this->assertSame($fixture, $object->getContents());
 
         $parsedContents = $object->getParsedContents();

tests/phpDocumentor/Reflection/DocBlock/Tag/CoversTagTest.php

@@ -28,11 +28,10 @@ class CoversTagTest extends \PHPUnit_Framework_TestCase
      *
      * @param string $type
      * @param string $content
-     * @param string $exName
      * @param string $exContent
      * @param string $exReference
      *
-     * @covers \phpDocumentor\Reflection\DocBlock\Tag\CoversTag::__construct
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag\CoversTag
      * @dataProvider provideDataForConstuctor
      *
      * @return void
@@ -40,22 +39,16 @@ class CoversTagTest extends \PHPUnit_Framework_TestCase
     public function testConstructorParesInputsIntoCorrectFields(
         $type,
         $content,
-        $exName,
         $exContent,
         $exDescription,
         $exReference
     ) {
         $tag = new CoversTag($type, $content);
 
-        $actualName        = $tag->getName();
+        $this->assertEquals($type, $tag->getName());
-        $actualContent     = $tag->getContent();
+        $this->assertEquals($exContent, $tag->getContent());
-        $actualDescription = $tag->getDescription();
+        $this->assertEquals($exDescription, $tag->getDescription());
-        $actualReference   = $tag->getReference();
+        $this->assertEquals($exReference, $tag->getReference());
-
-        $this->assertEquals($exName, $actualName);
-        $this->assertEquals($exContent, $actualContent);
-        $this->assertEquals($exDescription, $actualDescription);
-        $this->assertEquals($exReference, $actualReference);
     }
 
     /**
@@ -65,28 +58,25 @@ class CoversTagTest extends \PHPUnit_Framework_TestCase
      */
     public function provideDataForConstuctor()
     {
-        // $type, $content, $exName, $exContent, $exDescription, $exReference
+        // $type, $content, $exContent, $exDescription, $exReference
         return array(
             array(
-                'uses',
+                'covers',
                 'Foo::bar()',
-                'uses',
                 'Foo::bar()',
                 '',
                 'Foo::bar()'
             ),
             array(
-                'uses',
+                'covers',
                 'Foo::bar() Testing',
-                'uses',
                 'Foo::bar() Testing',
                 'Testing',
                 'Foo::bar()',
             ),
             array(
-                'uses',
+                'covers',
                 'Foo::bar() Testing comments',
-                'uses',
                 'Foo::bar() Testing comments',
                 'Testing comments',
                 'Foo::bar()',

tests/phpDocumentor/Reflection/DocBlock/Tag/LinkTagTest.php

@@ -28,12 +28,12 @@ class LinkTagTest extends \PHPUnit_Framework_TestCase
      *
      * @param string $type
      * @param string $content
-     * @param string $exName
      * @param string $exContent
      * @param string $exDescription
      * @param string $exLink
      *
      * @covers \phpDocumentor\Reflection\DocBlock\Tag\LinkTag::__construct
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag\LinkTag::getLink
      * @dataProvider provideDataForConstuctor
      *
      * @return void
@@ -41,22 +41,16 @@ class LinkTagTest extends \PHPUnit_Framework_TestCase
     public function testConstructorParesInputsIntoCorrectFields(
         $type,
         $content,
-        $exName,
         $exContent,
         $exDescription,
         $exLink
     ) {
         $tag = new LinkTag($type, $content);
 
-        $actualName        = $tag->getName();
+        $this->assertEquals($type, $tag->getName());
-        $actualContent     = $tag->getContent();
+        $this->assertEquals($exContent, $tag->getContent());
-        $actualDescription = $tag->getDescription();
+        $this->assertEquals($exDescription, $tag->getDescription());
-        $actualLink        = $tag->getLink();
+        $this->assertEquals($exLink, $tag->getLink());
-
-        $this->assertEquals($exName, $actualName);
-        $this->assertEquals($exContent, $actualContent);
-        $this->assertEquals($exDescription, $actualDescription);
-        $this->assertEquals($exLink, $actualLink);
     }
 
     /**
@@ -66,12 +60,11 @@ class LinkTagTest extends \PHPUnit_Framework_TestCase
      */
     public function provideDataForConstuctor()
     {
-        // $type, $content, $exName, $exContent, $exDescription, $exLink
+        // $type, $content, $exContent, $exDescription, $exLink
         return array(
             array(
                 'link',
                 'http://www.phpdoc.org/',
-                'link',
                 'http://www.phpdoc.org/',
                 'http://www.phpdoc.org/',
                 'http://www.phpdoc.org/'
@@ -79,7 +72,6 @@ class LinkTagTest extends \PHPUnit_Framework_TestCase
             array(
                 'link',
                 'http://www.phpdoc.org/ Testing',
-                'link',
                 'http://www.phpdoc.org/ Testing',
                 'Testing',
                 'http://www.phpdoc.org/'
@@ -87,7 +79,6 @@ class LinkTagTest extends \PHPUnit_Framework_TestCase
             array(
                 'link',
                 'http://www.phpdoc.org/ Testing comments',
-                'link',
                 'http://www.phpdoc.org/ Testing comments',
                 'Testing comments',
                 'http://www.phpdoc.org/'

tests/phpDocumentor/Reflection/DocBlock/Tag/MethodTagTest.php

@@ -23,17 +23,21 @@ namespace phpDocumentor\Reflection\DocBlock\Tag;
 class MethodTagTest extends \PHPUnit_Framework_TestCase
 {
     /**
-     * @param string $signature       The signature to test
+     * @param string $signature       The signature to test.
      * @param bool   $valid           Whether the given signature is expected to
      *     be valid.
      * @param string $expected_name   The method name that is expected from this
-     *     signature
+     *     signature.
      * @param string $expected_return The return type that is expected from this
-     *     signature
+     *     signature.
-     * @param bool   $has_params      whether this signature features parameters.
+     * @param bool   $paramCount      Number of parameters in the signature.
      * @param string $description     The short description mentioned in the
      *     signature.
      * 
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag\MethodTag::__construct
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag\MethodTag::getMethodName
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag\MethodTag::getArguments
+     * 
      * @dataProvider getTestSignatures
      *
      * @return void
@@ -43,7 +47,7 @@ class MethodTagTest extends \PHPUnit_Framework_TestCase
         $valid,
         $expected_name,
         $expected_return,
-        $has_params,
+        $paramCount,
         $description
     ) {
         ob_start();
@@ -63,11 +67,7 @@ class MethodTagTest extends \PHPUnit_Framework_TestCase
         $this->assertEquals($expected_name, $tag->getMethodName());
         $this->assertEquals($expected_return, $tag->getType());
         $this->assertEquals($description, $tag->getDescription());
-        $this->assertSame(
+        $this->assertCount($paramCount, $tag->getArguments());
-            $has_params,
-            (bool)(count($tag->getArguments()) > 0),
-            'Number of found arguments should exceed 0'
-        );
     }
 
     public function getTestSignatures()
@@ -75,55 +75,55 @@ class MethodTagTest extends \PHPUnit_Framework_TestCase
         return array(
             array(
                 'foo',
-                false, 'foo', '', false, ''
+                false, 'foo', '', 0, ''
             ),
             array(
                 'foo()',
-                true, 'foo', 'void', false, ''
+                true, 'foo', 'void', 0, ''
             ),
             array(
                 'foo() description',
-                true, 'foo', 'void', false, 'description'
+                true, 'foo', 'void', 0, 'description'
             ),
             array(
                 'int foo()',
-                true, 'foo', 'int', false, ''
+                true, 'foo', 'int', 0, ''
             ),
             array(
                 'int foo() description',
-                true, 'foo', 'int', false, 'description'
+                true, 'foo', 'int', 0, 'description'
             ),
             array(
                 'int foo($a, $b)',
-                true, 'foo', 'int', true, ''
+                true, 'foo', 'int', 2, ''
             ),
             array(
                 'int foo() foo(int $a, int $b)',
-                true, 'foo', 'int', true, ''
+                true, 'foo', 'int', 2, ''
             ),
             array(
                 'int foo(int $a, int $b)',
-                true, 'foo', 'int', true, ''
+                true, 'foo', 'int', 2, ''
             ),
             array(
                 'null|int foo(int $a, int $b)',
-                true, 'foo', 'null|int', true, ''
+                true, 'foo', 'null|int', 2, ''
             ),
             array(
                 'int foo(null|int $a, int $b)',
-                true, 'foo', 'int', true, ''
+                true, 'foo', 'int', 2, ''
             ),
             array(
                 '\Exception foo() foo(Exception $a, Exception $b)',
-                true, 'foo', '\Exception', true, ''
+                true, 'foo', '\Exception', 2, ''
             ),
             array(
                 'int foo() foo(Exception $a, Exception $b) description',
-                true, 'foo', 'int', true, 'description'
+                true, 'foo', 'int', 2, 'description'
             ),
             array(
                 'int foo() foo(\Exception $a, \Exception $b) description',
-                true, 'foo', 'int', true, 'description'
+                true, 'foo', 'int', 2, 'description'
             ),
         );
     }

tests/phpDocumentor/Reflection/DocBlock/Tag/ParamTagTest.php

@@ -29,10 +29,12 @@ class ParamTagTest extends \PHPUnit_Framework_TestCase
      * @param string $type
      * @param string $content
      * @param string $extractedType
+     * @param string $extractedTypes
      * @param string $extractedVarName
      * @param string $extractedDescription
      *
      * @covers \phpDocumentor\Reflection\DocBlock\Tag\ParamTag::__construct
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag\ParamTag::getVariableName
      *
      * @dataProvider provideDataForConstructor
      *
@@ -42,12 +44,15 @@ class ParamTagTest extends \PHPUnit_Framework_TestCase
         $type,
         $content,
         $extractedType,
+        $extractedTypes,
         $extractedVarName,
         $extractedDescription
     ) {
         $tag = new ParamTag($type, $content);
 
-        $this->assertEquals($extractedType, $tag->getTypes());
+        $this->assertEquals($type, $tag->getName());
+        $this->assertEquals($extractedType, $tag->getType());
+        $this->assertEquals($extractedTypes, $tag->getTypes());
         $this->assertEquals($extractedVarName, $tag->getVariableName());
         $this->assertEquals($extractedDescription, $tag->getDescription());
     }
@@ -60,17 +65,56 @@ class ParamTagTest extends \PHPUnit_Framework_TestCase
     public function provideDataForConstructor()
     {
         return array(
-            array('param', 'int', array('int'), '', ''),
+            array('param', 'int', 'int', array('int'), '', ''),
-            array('param', '$bob', array(), '$bob', ''),
+            array('param', '$bob', '', array(), '$bob', ''),
             array(
-                'param', 'int Number of bobs', array('int'), '',
+                'param',
+                'int Number of bobs',
+                'int',
+                array('int'),
+                '',
                 'Number of bobs'
             ),
-            array('param', 'int $bob', array('int'), '$bob', ''),
             array(
-                'param', 'int $bob Number of bobs', array('int'), '$bob',
+                'param',
+                'int $bob',
+                'int',
+                array('int'),
+                '$bob',
+                ''
+            ),
+            array(
+                'param',
+                'int $bob Number of bobs',
+                'int',
+                array('int'),
+                '$bob',
                 'Number of bobs'
             ),
+            array(
+                'param',
+                "int Description \n on multiple lines",
+                'int',
+                array('int'),
+                '',
+                "Description \n on multiple lines"
+            ),
+            array(
+                'param',
+                "int \n\$bob Variable name on a new line",
+                'int',
+                array('int'),
+                '$bob',
+                "Variable name on a new line"
+            ),
+            array(
+                'param',
+                "\nint \$bob Type on a new line",
+                'int',
+                array('int'),
+                '$bob',
+                "Type on a new line"
+            )
         );
     }
 }

tests/phpDocumentor/Reflection/DocBlock/Tag/ReturnTagTest.php

@@ -20,30 +20,38 @@ namespace phpDocumentor\Reflection\DocBlock\Tag;
  * @license   http://www.opensource.org/licenses/mit-license.php MIT
  * @link      http://phpdoc.org
  */
-class ReturnTagTest extends ParamTagTest
+class ReturnTagTest extends \PHPUnit_Framework_TestCase
 {
     /**
      * Test that the \phpDocumentor\Reflection\DocBlock\Tag\ReturnTag can
      * understand the @return DocBlock.
      *
+     * @param string $type
      * @param string $content
      * @param string $extractedType
+     * @param string $extractedTypes
      * @param string $extractedDescription
      *
      * @covers \phpDocumentor\Reflection\DocBlock\Tag\ReturnTag::__construct
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag\ReturnTag::getType
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag\ReturnTag::getTypes
      *
      * @dataProvider provideDataForConstructor
      *
      * @return void
      */
     public function testConstructorParsesInputsIntoCorrectFields(
+        $type,
         $content,
         $extractedType,
+        $extractedTypes,
         $extractedDescription
     ) {
-        $tag = new ReturnTag('return', $content);
+        $tag = new ReturnTag($type, $content);
 
-        $this->assertEquals($extractedType, $tag->getTypes());
+        $this->assertEquals($type, $tag->getName());
+        $this->assertEquals($extractedType, $tag->getType());
+        $this->assertEquals($extractedTypes, $tag->getTypes());
         $this->assertEquals($extractedDescription, $tag->getDescription());
     }
 
@@ -55,9 +63,36 @@ class ReturnTagTest extends ParamTagTest
     public function provideDataForConstructor()
     {
         return array(
-            array('', array(), ''),
+            array('return', '', '', array(), ''),
-            array('int', array('int'), ''),
+            array('return', 'int', 'int', array('int'), ''),
-            array('int Number of Bobs', array('int'), 'Number of Bobs'),
+            array(
+                'return',
+                'int Number of Bobs',
+                'int',
+                array('int'),
+                'Number of Bobs'
+            ),
+            array(
+                'return',
+                'int|double Number of Bobs',
+                'int|double',
+                array('int', 'double'),
+                'Number of Bobs'
+            ),
+            array(
+                'return',
+                "int Number of \n Bobs",
+                'int',
+                array('int'),
+                "Number of \n Bobs"
+            ),
+            array(
+                'return',
+                " int Number of Bobs",
+                'int',
+                array('int'),
+                "Number of Bobs"
+            )
         );
     }
 }

tests/phpDocumentor/Reflection/DocBlock/Tag/SeeTagTest.php

@@ -28,11 +28,11 @@ class SeeTagTest extends \PHPUnit_Framework_TestCase
      *
      * @param string $type
      * @param string $content
-     * @param string $exName
      * @param string $exContent
      * @param string $exReference
      *
      * @covers \phpDocumentor\Reflection\DocBlock\Tag\SeeTag::__construct
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag\SeeTag::getReference
      * @dataProvider provideDataForConstuctor
      *
      * @return void
@@ -40,22 +40,16 @@ class SeeTagTest extends \PHPUnit_Framework_TestCase
     public function testConstructorParesInputsIntoCorrectFields(
         $type,
         $content,
-        $exName,
         $exContent,
         $exDescription,
         $exReference
     ) {
         $tag = new SeeTag($type, $content);
 
-        $actualName        = $tag->getName();
+        $this->assertEquals($type, $tag->getName());
-        $actualContent     = $tag->getContent();
+        $this->assertEquals($exContent, $tag->getContent());
-        $actualDescription = $tag->getDescription();
+        $this->assertEquals($exDescription, $tag->getDescription());
-        $actualReference   = $tag->getReference();
+        $this->assertEquals($exReference, $tag->getReference());
-
-        $this->assertEquals($exName, $actualName);
-        $this->assertEquals($exContent, $actualContent);
-        $this->assertEquals($exDescription, $actualDescription);
-        $this->assertEquals($exReference, $actualReference);
     }
 
     /**
@@ -65,28 +59,25 @@ class SeeTagTest extends \PHPUnit_Framework_TestCase
      */
     public function provideDataForConstuctor()
     {
-        // $type, $content, $exName, $exContent, $exDescription, $exReference
+        // $type, $content, $exContent, $exDescription, $exReference
         return array(
             array(
-                'uses',
+                'see',
                 'Foo::bar()',
-                'uses',
                 'Foo::bar()',
                 '',
                 'Foo::bar()'
             ),
             array(
-                'uses',
+                'see',
                 'Foo::bar() Testing',
-                'uses',
                 'Foo::bar() Testing',
                 'Testing',
                 'Foo::bar()',
             ),
             array(
-                'uses',
+                'see',
                 'Foo::bar() Testing comments',
-                'uses',
                 'Foo::bar() Testing comments',
                 'Testing comments',
                 'Foo::bar()',

tests/phpDocumentor/Reflection/DocBlock/Tag/ThrowsTagTest.php

@@ -0,0 +1,96 @@
+<?php
+/**
+ * phpDocumentor Return tag test.
+ * 
+ * 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;
+
+/**
+ * Test class for \phpDocumentor\Reflection\DocBlock\ReturnTag.
+ *
+ * @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
+ */
+class ThrowsTagTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * Test that the \phpDocumentor\Reflection\DocBlock\Tag\ReturnTag can
+     * understand the @return DocBlock.
+     *
+     * @param string $type
+     * @param string $content
+     * @param string $extractedType
+     * @param string $extractedTypes
+     * @param string $extractedDescription
+     *
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag\ThrowsTag
+     *
+     * @dataProvider provideDataForConstructor
+     *
+     * @return void
+     */
+    public function testConstructorParsesInputsIntoCorrectFields(
+        $type,
+        $content,
+        $extractedType,
+        $extractedTypes,
+        $extractedDescription
+    ) {
+        $tag = new ThrowsTag($type, $content);
+
+        $this->assertEquals($type, $tag->getName());
+        $this->assertEquals($extractedType, $tag->getType());
+        $this->assertEquals($extractedTypes, $tag->getTypes());
+        $this->assertEquals($extractedDescription, $tag->getDescription());
+    }
+
+    /**
+     * Data provider for testConstructorParsesInputsIntoCorrectFields()
+     *
+     * @return array
+     */
+    public function provideDataForConstructor()
+    {
+        return array(
+            array('throws', '', '', array(), ''),
+            array('throws', 'int', 'int', array('int'), ''),
+            array(
+                'throws',
+                'int Number of Bobs',
+                'int',
+                array('int'),
+                'Number of Bobs'
+            ),
+            array(
+                'throws',
+                'int|double Number of Bobs',
+                'int|double',
+                array('int', 'double'),
+                'Number of Bobs'
+            ),
+            array(
+                'throws',
+                "int Number of \n Bobs",
+                'int',
+                array('int'),
+                "Number of \n Bobs"
+            ),
+            array(
+                'throws',
+                " int Number of Bobs",
+                'int',
+                array('int'),
+                "Number of Bobs"
+            )
+        );
+    }
+}

tests/phpDocumentor/Reflection/DocBlock/Tag/UsesTagTest.php

@@ -28,11 +28,10 @@ class UsesTagTest extends \PHPUnit_Framework_TestCase
      *
      * @param string $type
      * @param string $content
-     * @param string $exName
      * @param string $exContent
      * @param string $exReference
      *
-     * @covers \phpDocumentor\Reflection\DocBlock\Tag\UsesTag::__construct
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag\UsesTag
      * @dataProvider provideDataForConstuctor
      *
      * @return void
@@ -40,22 +39,16 @@ class UsesTagTest extends \PHPUnit_Framework_TestCase
     public function testConstructorParesInputsIntoCorrectFields(
         $type,
         $content,
-        $exName,
         $exContent,
         $exDescription,
         $exReference
     ) {
         $tag = new UsesTag($type, $content);
 
-        $actualName        = $tag->getName();
+        $this->assertEquals($type, $tag->getName());
-        $actualContent     = $tag->getContent();
+        $this->assertEquals($exContent, $tag->getContent());
-        $actualDescription = $tag->getDescription();
+        $this->assertEquals($exDescription, $tag->getDescription());
-        $actualReference   = $tag->getReference();
+        $this->assertEquals($exReference, $tag->getReference());
-
-        $this->assertEquals($exName, $actualName);
-        $this->assertEquals($exContent, $actualContent);
-        $this->assertEquals($exDescription, $actualDescription);
-        $this->assertEquals($exReference, $actualReference);
     }
 
     /**
@@ -65,12 +58,11 @@ class UsesTagTest extends \PHPUnit_Framework_TestCase
      */
     public function provideDataForConstuctor()
     {
-        // $type, $content, $exName, $exContent, $exDescription, $exReference
+        // $type, $content, $exContent, $exDescription, $exReference
         return array(
             array(
                 'uses',
                 'Foo::bar()',
-                'uses',
                 'Foo::bar()',
                 '',
                 'Foo::bar()'
@@ -78,7 +70,6 @@ class UsesTagTest extends \PHPUnit_Framework_TestCase
             array(
                 'uses',
                 'Foo::bar() Testing',
-                'uses',
                 'Foo::bar() Testing',
                 'Testing',
                 'Foo::bar()',
@@ -86,7 +77,6 @@ class UsesTagTest extends \PHPUnit_Framework_TestCase
             array(
                 'uses',
                 'Foo::bar() Testing comments',
-                'uses',
                 'Foo::bar() Testing comments',
                 'Testing comments',
                 'Foo::bar()',

tests/phpDocumentor/Reflection/DocBlock/Tag/VarTagTest.php

@@ -46,6 +46,7 @@ class VarTagTest extends \PHPUnit_Framework_TestCase
     ) {
         $tag = new VarTag($type, $content);
 
+        $this->assertEquals($type, $tag->getName());
         $this->assertEquals($exType, $tag->getType());
         $this->assertEquals($exVariable, $tag->getVariableName());
         $this->assertEquals($exDescription, $tag->getDescription());
@@ -58,7 +59,7 @@ class VarTagTest extends \PHPUnit_Framework_TestCase
      */
     public function provideDataForConstuctor()
     {
-        // $type, $content
+        // $type, $content, $exType, $exVariable, $exDescription
         return array(
             array(
                 'var',
@@ -81,6 +82,13 @@ class VarTagTest extends \PHPUnit_Framework_TestCase
                 '$bob',
                 'Number of bobs'
             ),
+            array(
+                'var',
+                '',
+                '',
+                '',
+                ''
+            ),
         );
     }
 }

tests/phpDocumentor/Reflection/DocBlock/TagTest.php

@@ -0,0 +1,233 @@
+<?php
+/**
+ * phpDocumentor Var Tag Test
+ * 
+ * PHP version 5.3
+ *
+ * @author    Daniel O'Connor <[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;
+
+/**
+ * Test class for \phpDocumentor\Reflection\DocBlock\Tag\VarTag
+ *
+ * @author    Daniel O'Connor <[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
+ */
+class TagTest extends \PHPUnit_Framework_TestCase
+{
+    
+    /**
+     * @expectedException \InvalidArgumentException
+     * 
+     * @return void
+     */
+    public function testInvalidTagLine()
+    {
+        Tag::createInstance('Invalid tag line');
+    }
+
+    /**
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag::registerTagHandler
+     * 
+     * @return void
+     */
+    public function testTagHandlerUnregistration()
+    {
+        $currentHandler = __NAMESPACE__ . '\Tag\VarTag';
+        $tagPreUnreg = Tag::createInstance('@var mixed');
+        $this->assertInstanceOf(
+            $currentHandler,
+            $tagPreUnreg
+        );
+        $this->assertInstanceOf(
+            __NAMESPACE__ . '\Tag',
+            $tagPreUnreg
+        );
+
+        Tag::registerTagHandler('var', null);
+
+        $tagPostUnreg = Tag::createInstance('@var mixed');
+        $this->assertNotInstanceOf(
+            $currentHandler,
+            $tagPostUnreg
+        );
+        $this->assertInstanceOf(
+            __NAMESPACE__ . '\Tag',
+            $tagPostUnreg
+        );
+
+        Tag::registerTagHandler('var', $currentHandler);
+    }
+
+    /**
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag::registerTagHandler
+     * 
+     * @return void
+     */
+    public function testTagHandlerCorrectRegistration()
+    {
+        if (0 == ini_get('allow_url_include')) {
+            $this->markTestSkipped('"data" URIs for includes are required.');
+        }
+        $currentHandler = __NAMESPACE__ . '\Tag\VarTag';
+        $tagPreUnreg = Tag::createInstance('@var mixed');
+        $this->assertInstanceOf(
+            $currentHandler,
+            $tagPreUnreg
+        );
+        $this->assertInstanceOf(
+            __NAMESPACE__ . '\Tag',
+            $tagPreUnreg
+        );
+
+        require 'data:text/plain;base64,'. base64_encode(
+<<<TAG_HANDLER
+<?php
+    class MyVarHandler extends \phpDocumentor\Reflection\DocBlock\Tag {}
+TAG_HANDLER
+        );
+
+        $this->assertTrue(Tag::registerTagHandler('var', '\MyVarHandler'));
+
+        $tagPostUnreg = Tag::createInstance('@var mixed');
+        $this->assertNotInstanceOf(
+            $currentHandler,
+            $tagPostUnreg
+        );
+        $this->assertInstanceOf(
+            __NAMESPACE__ . '\Tag',
+            $tagPostUnreg
+        );
+        $this->assertInstanceOf(
+            '\MyVarHandler',
+            $tagPostUnreg
+        );
+
+        $this->assertTrue(Tag::registerTagHandler('var', $currentHandler));
+    }
+
+    /**
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag::registerTagHandler
+     * 
+     * @return void
+     */
+    public function testNonExistentTagHandlerRegistration()
+    {
+        $currentHandler = __NAMESPACE__ . '\Tag\VarTag';
+        $tagPreReg = Tag::createInstance('@var mixed');
+        $this->assertInstanceOf(
+            $currentHandler,
+            $tagPreReg
+        );
+        $this->assertInstanceOf(
+            __NAMESPACE__ . '\Tag',
+            $tagPreReg
+        );
+
+        $this->assertFalse(Tag::registerTagHandler('var', 'Non existent'));
+
+        $tagPostReg = Tag::createInstance('@var mixed');
+        $this->assertInstanceOf(
+            $currentHandler,
+            $tagPostReg
+        );
+        $this->assertInstanceOf(
+            __NAMESPACE__ . '\Tag',
+            $tagPostReg
+        );
+    }
+
+    /**
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag::registerTagHandler
+     * 
+     * @return void
+     */
+    public function testIncompatibleTagHandlerRegistration()
+    {
+        $currentHandler = __NAMESPACE__ . '\Tag\VarTag';
+        $tagPreReg = Tag::createInstance('@var mixed');
+        $this->assertInstanceOf(
+            $currentHandler,
+            $tagPreReg
+        );
+        $this->assertInstanceOf(
+            __NAMESPACE__ . '\Tag',
+            $tagPreReg
+        );
+
+        $this->assertFalse(
+            Tag::registerTagHandler('var', __NAMESPACE__ . '\TagTest')
+        );
+
+        $tagPostReg = Tag::createInstance('@var mixed');
+        $this->assertInstanceOf(
+            $currentHandler,
+            $tagPostReg
+        );
+        $this->assertInstanceOf(
+            __NAMESPACE__ . '\Tag',
+            $tagPostReg
+        );
+    }
+
+    /**
+     * Test that the \phpDocumentor\Reflection\DocBlock\Tag\VarTag can
+     * understand the @var doc block.
+     *
+     * @param string $type
+     * @param string $content
+     * @param string $exDescription
+     *
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag::__construct
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag::getDescription
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag::getContent
+     * @dataProvider provideDataForConstuctor
+     *
+     * @return void
+     */
+    public function testConstructorParesInputsIntoCorrectFields(
+        $type,
+        $content,
+        $exDescription
+    ) {
+        $tag = new Tag($type, $content);
+
+        $this->assertEquals($type, $tag->getName());
+        $this->assertEquals($content, $tag->getContent());
+        $this->assertEquals($exDescription, $tag->getDescription());
+    }
+
+    /**
+     * Data provider for testConstructorParesInputsIntoCorrectFields
+     *
+     * @return array
+     */
+    public function provideDataForConstuctor()
+    {
+        // $type, $content, $exDescription
+        return array(
+            array(
+                'unknown',
+                'some content',
+                'some content',
+            ),
+            array(
+                'unknown',
+                '',
+                '',
+            ),
+            array(
+                '',
+                'unknown',
+                'unknown',
+            )
+        );
+    }
+}

tests/phpDocumentor/Reflection/DocBlock/Type/CollectionTest.php

@@ -39,6 +39,23 @@ class CollectionTest extends \PHPUnit_Framework_TestCase
         $this->assertCount(0, $collection->getNamespaceAliases());
     }
 
+    /**
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::__construct
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::setNamespace
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::getNamespace
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::getNamespaceAliases
+     * 
+     * @return void
+     */
+    public function testGlobalIgnore()
+    {
+        $collection = new Collection();
+        $collection->setNamespace('global');
+        $this->assertCount(0, $collection);
+        $this->assertEquals('\\', $collection->getNamespace());
+        $this->assertCount(0, $collection->getNamespaceAliases());
+    }
+
     /**
      * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::__construct
      * 
@@ -118,8 +135,8 @@ class CollectionTest extends \PHPUnit_Framework_TestCase
     }
 
     /**
-     * @param $fixture
+     * @param string $fixture
-     * @param $expected
+     * @param array  $expected
      *
      * @dataProvider provideTypesToExpand
      * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::add
@@ -137,8 +154,8 @@ class CollectionTest extends \PHPUnit_Framework_TestCase
     }
 
     /**
-     * @param $fixture
+     * @param string $fixture
-     * @param $expected
+     * @param array  $expected
      *
      * @dataProvider provideTypesToExpandWithoutNamespace
      * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::add

tests/phpDocumentor/Reflection/DocBlockTest.php

@@ -34,7 +34,11 @@ class DocBlockTest extends \PHPUnit_Framework_TestCase
  * @return void
  */
 DOCBLOCK;
-        $object = new DocBlock($fixture);
+        $object = new DocBlock(
+            $fixture,
+            '\MyNamespace',
+            array('PHPDoc' => '\phpDocumentor')
+        );
         $this->assertEquals(
             'This is a short description.',
             $object->getShortDescription()
@@ -43,12 +47,62 @@ DOCBLOCK;
             'This is a long description.',
             $object->getLongDescription()->getContents()
         );
-        $this->assertEquals(2, count($object->getTags()));
+        $this->assertCount(2, $object->getTags());
+        $this->assertTrue($object->hasTag('see'));
+        $this->assertTrue($object->hasTag('return'));
+        $this->assertFalse($object->hasTag('category'));
+        
+        $this->assertSame('\MyNamespace', $object->getNamespace());
+        $this->assertSame(
+            array('PHPDoc' => '\phpDocumentor'),
+            $object->getNamespaceAliases()
+        );
+    }
+
+    /**
+     * @covers \phpDocumentor\Reflection\DocBlock::splitDocBlock
+     * 
+     * @return void
+     */
+    public function testConstructWithTagsOnly()
+    {
+        $fixture = <<<DOCBLOCK
+/**
+ * @see \MyClass
+ * @return void
+ */
+DOCBLOCK;
+        $object = new DocBlock($fixture);
+        $this->assertEquals('', $object->getShortDescription());
+        $this->assertEquals('', $object->getLongDescription()->getContents());
+        $this->assertCount(2, $object->getTags());
         $this->assertTrue($object->hasTag('see'));
         $this->assertTrue($object->hasTag('return'));
         $this->assertFalse($object->hasTag('category'));
     }
 
+    /**
+     * @covers \phpDocumentor\Reflection\DocBlock::cleanInput
+     * 
+     * @return void
+     */
+    public function testConstructOneLiner()
+    {
+        $fixture = '/** Short description and nothing more. */';
+        $object = new DocBlock($fixture);
+        $this->assertEquals(
+            'Short description and nothing more.',
+            $object->getShortDescription()
+        );
+        $this->assertEquals('', $object->getLongDescription()->getContents());
+        $this->assertCount(0, $object->getTags());
+    }
+
+    /**
+     * @covers \phpDocumentor\Reflection\DocBlock::__construct
+     * 
+     * @return void
+     */
     public function testConstructFromReflector()
     {
         $object = new DocBlock(new \ReflectionClass($this));
@@ -57,7 +111,7 @@ DOCBLOCK;
             $object->getShortDescription()
         );
         $this->assertEquals('', $object->getLongDescription()->getContents());
-        $this->assertEquals(4, count($object->getTags()));
+        $this->assertCount(4, $object->getTags());
         $this->assertTrue($object->hasTag('author'));
         $this->assertTrue($object->hasTag('copyright'));
         $this->assertTrue($object->hasTag('license'));
@@ -67,10 +121,12 @@ DOCBLOCK;
 
     /**
      * @expectedException \InvalidArgumentException
+     * 
+     * @return void
      */
     public function testExceptionOnInvalidObject()
     {
-        $object = new DocBlock($this);
+        new DocBlock($this);
     }
 
     public function testDotSeperation()
@@ -93,6 +149,32 @@ DOCBLOCK;
         );
     }
 
+    /**
+     * @covers \phpDocumentor\Reflection\DocBlock::parseTags
+     * @expectedException \LogicException
+     * 
+     * @return void
+     */
+    public function testInvalidTagBlock()
+    {
+        if (0 == ini_get('allow_url_include')) {
+            $this->markTestSkipped('"data" URIs for includes are required.');
+        }
+
+        require 'data:text/plain;base64,'. base64_encode(
+            <<<DOCBLOCK_EXTENSION
+<?php
+class MyReflectionDocBlock extends \phpDocumentor\Reflection\DocBlock {
+    protected function splitDocBlock(\$comment) {
+        return array('', '', 'Invalid tag block');
+    }
+}
+DOCBLOCK_EXTENSION
+        );
+        new \MyReflectionDocBlock('');
+        
+    }
+
     public function testTagCaseSensitivity()
     {
         $fixture = <<<DOCBLOCK
@@ -115,7 +197,7 @@ DOCBLOCK;
             $object->getLongDescription()->getContents()
         );
         $tags = $object->getTags();
-        $this->assertEquals(2, count($tags));
+        $this->assertCount(2, $tags);
         $this->assertTrue($object->hasTag('method'));
         $this->assertTrue($object->hasTag('Method'));
         $this->assertInstanceOf(
@@ -133,88 +215,74 @@ DOCBLOCK;
     }
 
     /**
-     * Tests whether a type is expanded with the given namespace and that a
+     * @depends testConstructFromReflector
-     * keyword is not expanded.
+     * @covers \phpDocumentor\Reflection\DocBlock::getTagsByName
-     *
+     * 
-     * @covers \phpDocumentor\Reflection\DocBlock::expandType()
-     *
      * @return void
      */
-    public function testExpandTypeUsingNamespace()
+    public function testGetTagsByNameZeroAndOneMatch()
     {
-        $docblock = new DocBlock('', '\My\Namespace');
+        $object = new DocBlock(new \ReflectionClass($this));
-        $this->assertEquals('\My\Namespace\Mine', $docblock->expandType('Mine'));
+        $this->assertEmpty($object->getTagsByName('category'));
+        $this->assertCount(1, $object->getTagsByName('author'));
     }
 
     /**
-     * Tests whether a type is expanded when no namespace is given.
+     * @depends testConstructWithTagsOnly
-     *
+     * @covers \phpDocumentor\Reflection\DocBlock::parseTags
-     * @covers \phpDocumentor\Reflection\DocBlock::expandType()
+     * 
-     *
      * @return void
      */
-    public function testExpandTypeWithoutNamespace()
+    public function testParseMultilineTag()
     {
-        $docblock = new DocBlock('');
+        $fixture = <<<DOCBLOCK
-        $this->assertEquals('\Mine', $docblock->expandType('Mine'));
+/**
+ * @return void Content on
+ *     multiple lines.
+ */
+DOCBLOCK;
+        $object = new DocBlock($fixture);
+        $this->assertCount(1, $object->getTags());
     }
 
     /**
-     * Tests whether a type is expanded with the given namespace when an alias
+     * @depends testConstructWithTagsOnly
-     * is provided.
+     * @covers \phpDocumentor\Reflection\DocBlock::parseTags
-     *
+     * 
-     * @covers \phpDocumentor\Reflection\DocBlock::expandType()
-     *
      * @return void
      */
-    public function testExpandTypeUsingNamespaceAlias()
+    public function testParseMultilineTagWithLineBreaks()
     {
-        $docblock = new DocBlock(
+        $fixture = <<<DOCBLOCK
-            '',
+/**
-            '\My\Namespace',
+ * @return void Content on
-            array('Alias' => '\My\Namespace\Alias')
+ *     multiple lines.
-        );
+ *
-
+ *     One more, after the break.
-        // first try a normal resolution without alias
+ */
-        $this->assertEquals(
+DOCBLOCK;
-            '\My\Namespace\Al',
+        $object = new DocBlock($fixture);
-            $docblock->expandType('Al')
+        $this->assertCount(1, $object->getTags());
-        );
-
-        // try to use the alias
-        $this->assertEquals(
-            '\My\Namespace\Alias\Al',
-            $docblock->expandType('Alias\Al')
-        );
     }
 
     /**
-     * Tests whether the keywords that should not be converted are not converted.
+     * @depends testConstructWithTagsOnly
-     *
+     * @covers \phpDocumentor\Reflection\DocBlock::getTagsByName
-     * @param string $keyword The keyword that is to be tested; this is provided
+     * 
-     *     by the dataprovider.
-     *
-     * @covers \phpDocumentor\Reflection\DocBlock::expandType()
-     *
-     * @dataProvider getNonExpandableKeywordsForExpandType
-     *
      * @return void
      */
-    public function testThatExpandTypeDoesNotExpandAllKeywords($keyword)
+    public function testGetTagsByNameMultipleMatch()
     {
-        $docblock = new DocBlock('', '\My\Namespace');
+        $fixture = <<<DOCBLOCK
-        $this->assertSame($keyword, $docblock->expandType($keyword));
+/**
-    }
+ * @param string
-
+ * @param int
-    public function getNonExpandableKeywordsForExpandType()
+ * @return void
-    {
+ */
-        return array(
+DOCBLOCK;
-            array(null),
+        $object = new DocBlock($fixture);
-            array('string'), array('int'), array('integer'), array('bool'),
+        $this->assertEmpty($object->getTagsByName('category'));
-            array('boolean'), array('float'), array('double'), array('object'),
+        $this->assertCount(1, $object->getTagsByName('return'));
-            array('mixed'), array('array'), array('resource'), array('void'),
+        $this->assertCount(2, $object->getTagsByName('param'));
-            array('null'), array('callback'), array('false'), array('true'),
-            array('self'), array('$this'), array('callable')
-        );
     }
 }