Change behaviour of @param parsing

In issue report phpDocumentor/phpDocumentor2#620 @bobef reported that when he
used just a Type as content of the @param that it would be recognized as
description instead of the Type.

According to the unit tests this is correct behaviour but after reviewing the
pattern of the output his version is more consistent. As such I have altered
the behaviour to act as following:

If only one word is found after an @param (word means white-space bounded
series of characters) then interpret that as the type and not description.

During this item several issues in unit tests were fixed and a new 'Type'
Collection was introduced that is capable of expanding types based on a given
namespace and series of aliases.
This should be re-used in phpDocumentor's Transformer as a duplication exists
there with the expanding of the Types.

Please note: the suggested format by @bobef is not valid according to the
PHPDoc Standard but is provided for convenience.

.gitignore

@@ -1 +1,2 @@
-.idea
+.idea
+vendor

README.md

@@ -0,0 +1,57 @@
+The ReflectionDocBlock Component
+================================
+
+Introduction
+------------
+
+The ReflectionDocBlock component of phpDocumentor provides a DocBlock parser
+that is 100% compatible with the [PHPDoc standard](http://phpdoc.org/docs/latest).
+
+With this component can a library provide support for annotations via DocBlocks
+or otherwise retrieve information that is embedded in a DocBlock.
+
+> **Note**: *this is a core component of phpDocumentor and is constantly being
+> optimized for performance.*
+
+Installation
+------------
+
+You can install the component in the following ways:
+
+* Use the official Github repository (https://github.com/phpDocumentor/ReflectionDocBlock)
+* Via Composer (http://packagist.org/packages/phpdocumentor/reflection-docblock)
+
+Usage
+-----
+
+The ReflectionDocBlock component is designed to work in an identical fashion to
+PHP's own Reflection extension (http://php.net/manual/en/book.reflection.php).
+
+Parsing can be initiated by instantiating the
+`\phpDocumentor\Reflection\DocBlock()` class and passing it a string containing
+a DocBlock (including asterisks) or by passing an object supporting the
+`getDocComment()` method.
+
+> *Examples of objects having the `getDocComment()` method are the
+> `ReflectionClass` and the `ReflectionMethod` classes of the PHP
+> Reflection extension*
+
+Example:
+
+    $class = new ReflectionClass('MyClass');
+    $phpdoc = new \phpDocumentor\Reflection\DocBlock($class);
+
+or
+
+    $docblock = <<<DOCBLOCK
+    /**
+     * This is a short description.
+     *
+     * This is a *long* description.
+     *
+     * @return void
+     */
+    DOCBLOCK;
+
+    $phpdoc = new \phpDocumentor\Reflection\DocBlock($docblock);
+

composer.json

@@ -6,9 +6,10 @@
         {"name": "Mike van Riel", "email": "[email protected]"}
     ],
     "require": {
-        "php": ">=5.3.2"
+        "php": ">=5.3.2",
+        "dflydev/markdown": "1.0.*"
     },
     "autoload": {
-        "psr-0": {"phpDocumentor\\Reflection": "src/phpDocumentor"}
+        "psr-0": {"phpDocumentor": ["src/"]}
     }
 }

composer.lock

@@ -0,0 +1,67 @@
+{
+    "hash": "89c7387ec02d39de3c07849e525f95e4",
+    "packages": [
+        {
+            "name": "dflydev/markdown",
+            "version": "v1.0.2",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/dflydev/dflydev-markdown.git",
+                "reference": "v1.0.2"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://github.com/dflydev/dflydev-markdown/zipball/v1.0.2",
+                "reference": "v1.0.2",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=5.3"
+            },
+            "time": "2012-01-15 19:36:37",
+            "type": "library",
+            "installation-source": "dist",
+            "autoload": {
+                "psr-0": {
+                    "dflydev\\markdown": "src"
+                }
+            },
+            "license": [
+                "New BSD License"
+            ],
+            "authors": [
+                {
+                    "name": "Dragonfly Development Inc.",
+                    "email": "[email protected]",
+                    "homepage": "http://dflydev.com"
+                },
+                {
+                    "name": "Beau Simensen",
+                    "email": "[email protected]",
+                    "homepage": "http://beausimensen.com"
+                },
+                {
+                    "name": "Michel Fortin",
+                    "homepage": "http://michelf.com"
+                },
+                {
+                    "name": "John Gruber",
+                    "homepage": "http://daringfireball.net"
+                }
+            ],
+            "description": "PHP Markdown & Extra",
+            "homepage": "http://github.com/dflydev/dflydev-markdown",
+            "keywords": [
+                "markdown"
+            ]
+        }
+    ],
+    "packages-dev": null,
+    "aliases": [
+
+    ],
+    "minimum-stability": "stable",
+    "stability-flags": [
+
+    ]
+}

phpunit.xml.dist

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 
-<phpunit colors="true" strict="true">
+<phpunit colors="true" strict="true" bootstrap="vendor/autoload.php">
   <testsuites>
     <testsuite name="phpDocumentor\Reflection\DocBlock">
       <directory>./tests/</directory>

src/phpDocumentor/Reflection/DocBlock.php

@@ -36,14 +36,36 @@ class DocBlock implements \Reflector
      */
     protected $tags = array();
 
+    /** @var string the current namespace */
+    protected $namespace = '\\';
+
+    /** @var string[] List of namespace aliases => Fully Qualified Namespace */
+    protected $namespace_aliases = array();
+
     /**
      * Parses the given docblock and populates the member fields.
      *
-     * @param string|\Reflector $docblock A docblock comment (including asterisks)
+     * The constructor may also receive namespace information such as the
+     * current namespace and aliases. This information is used in the
+     * {@link expandType()} method to transform a relative Type into a FQCN.
+     *
+     * For example the param and return tags use this to expand their type
+     * information.
+     *
+     * @param \Reflector|string $docblock A docblock comment (including 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 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.
+     *
+     * @throws \InvalidArgumentException if the given argument does not have the
+     *     getDocComment method.
      */
-    public function __construct($docblock)
-    {
+    public function __construct(
+        $docblock, $namespace = '\\', $namespace_aliases = array()
+    ) {
         if (is_object($docblock)) {
             if (!method_exists($docblock, 'getDocComment')) {
                 throw new \InvalidArgumentException(
@@ -61,6 +83,9 @@ class DocBlock implements \Reflector
         $this->short_description = $short;
         $this->long_description = new DocBlock\LongDescription($long);
         $this->parseTags($tags);
+
+        $this->namespace = $namespace;
+        $this->namespace_aliases = $namespace_aliases;
     }
 
     /**
@@ -74,7 +99,7 @@ class DocBlock implements \Reflector
     {
         $comment = trim(
             preg_replace(
-                '#[ \t]*(?:\/\*\*|\*\/|\*)?[ \t]{0,1}(.*)?#', '$1', $comment
+                '#[ \t]*(?:\/\*\*|\*\/|\*)?[ \t]{0,1}(.*)?#u', '$1', $comment
             )
         );
 
@@ -108,7 +133,7 @@ class DocBlock implements \Reflector
         } else {
             // clears all extra horizontal whitespace from the line endings
             // to prevent parsing issues
-            $comment = preg_replace('~(?m)\h*$~', '', $comment);
+            $comment = preg_replace('~(?m)\h*$~u', '', $comment);
 
             /*
              * Splits the docblock into a short description, long description and
@@ -127,11 +152,11 @@ class DocBlock implements \Reflector
             preg_match(
                 '/(?x)
         \A (
-          [^\n]+
+          [^\n.]+
           (?:
-            (?! (?<=\.) \n | \n{2} ) # disallow the first seperator here
-            \n (?! [ \t]* @\pL ) # disallow second seperator
-            [^\n]+
+            (?! \. \s | \n{2} ) # disallow the first seperator here
+            [\n.] (?! [ \t]* @\pL ) # disallow second seperator
+            [^\n.]+
           )*
           \.?
         )
@@ -148,7 +173,7 @@ class DocBlock implements \Reflector
           )
         )?
         (\s+ [\s\S]*)? # everything that follows
-        /', $comment, $matches
+        /u', $comment, $matches
             );
             array_shift($matches);
         }
@@ -174,8 +199,6 @@ class DocBlock implements \Reflector
                 continue;
             }
 
-            $tag_line = ltrim($tag_line);
-
             if (isset($tag_line[0]) && ($tag_line[0] === '@')) {
                 $result[] = $tag_line;
             } else {
@@ -192,7 +215,9 @@ class DocBlock implements \Reflector
 
         // create proper Tag objects
         foreach ($result as $key => $tag_line) {
-            $result[$key] = DocBlock\Tag::createInstance($tag_line);
+            $tag = DocBlock\Tag::createInstance($tag_line);
+            $tag->setDocBlock($this);
+            $result[$key] = $tag;
         }
 
         $this->tags = $result;
@@ -271,6 +296,84 @@ 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'.
+     *     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.
      *
@@ -295,4 +398,16 @@ class DocBlock implements \Reflector
         return 'Not yet implemented';
     }
 
+    /**
+     * @return string
+     */
+    public function getNamespace()
+    {
+        return $this->namespace;
+    }
+
+    public function getNamespaceAliases()
+    {
+        return $this->namespace_aliases;
+    }
 }

src/phpDocumentor/Reflection/DocBlock/LongDescription.php

@@ -2,7 +2,7 @@
 /**
  * phpDocumentor
  *
- * PHP Version 5
+ * PHP Version 5.3
  *
  * @author    Mike van Riel <[email protected]>
  * @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com)
@@ -24,6 +24,9 @@ class LongDescription implements \Reflector
     /** @var string */
     protected $contents = '';
 
+    /** @var array The contents, as an array of strings and Tag objects. */
+    protected $parsedContents = null;
+
     /** @var \phpDocumentor\Reflection\DocBlock\Tags[] */
     protected $tags = array();
 
@@ -35,13 +38,6 @@ class LongDescription implements \Reflector
      */
     public function __construct($content)
     {
-        if (preg_match('/\{\@(.+?)\}/', $content, $matches)) {
-            array_shift($matches);
-            foreach ($matches as $tag) {
-                $this->tags[] = Tag::createInstance('@' . $tag);
-            }
-        }
-
         $this->contents = trim($content);
     }
 
@@ -55,6 +51,28 @@ class LongDescription implements \Reflector
         return $this->contents;
     }
 
+    /*
+     * Returns the parsed text of this description.
+     *
+     * @return array An array of strings and tag objects, in the order they
+     * occur within the description.
+     */
+    public function getParsedContents()
+    {
+        if (null === $this->parsedContents) {
+            $this->parsedContents = preg_split(
+                '/\{(\@.*?)\}/uS', $this->contents,
+                null, PREG_SPLIT_DELIM_CAPTURE
+            );
+            for ($i=1, $l = count($this->parsedContents); $i<$l; $i += 2) {
+                $this->parsedContents[$i] = Tag::createInstance(
+                    $this->parsedContents[$i]
+                );
+            }
+        }
+        return $this->parsedContents;
+    }
+
     /**
      * Return a formatted variant of the Long Description using MarkDown.
      *
@@ -78,7 +96,7 @@ class LongDescription implements \Reflector
             );
         }
 
-        if (class_exists('\dflydev\markdown\MarkdownExtraParser()')) {
+        if (class_exists('dflydev\markdown\MarkdownExtraParser')) {
             $md = new \dflydev\markdown\MarkdownExtraParser();
             $result = $md->transformMarkdown($result);
         }
@@ -86,16 +104,6 @@ class LongDescription implements \Reflector
         return trim($result);
     }
 
-    /**
-     * Returns a list of tags mentioned in the text.
-     *
-     * @return \phpDocumentor\Reflection\DocBlock\Tags[]
-     */
-    public function getTags()
-    {
-        return $this->tags;
-    }
-
     /**
      * Builds a string representation of this object.
      *

src/phpDocumentor/Reflection/DocBlock/Tag.php

@@ -24,16 +24,19 @@ class Tag implements \Reflector
     /** @var string Name of the tag */
     protected $tag = '';
 
-    /** @var string content of the tag */
+    /** @var string Content of the tag */
     protected $content = '';
 
-    /** @var string description of the content of this tag */
+    /** @var string Description of the content of this tag */
     protected $description = '';
+    
+    /** @var array The description, as an array of strings and Tag objects. */
+    protected $parsedDescription = null;
 
-    /** @var int line number of the tag */
+    /** @var int Line number of the tag */
     protected $line_number = 0;
 
-    /** @var object docblock class */
+    /** @var \phpDocumentor\Reflection\DocBlock docblock class */
     protected $docblock;
 
     /**
@@ -59,7 +62,7 @@ class Tag implements \Reflector
         $tag_name = str_replace(
             ' ', '', ucwords(str_replace('-', ' ', $matches[1]))
         ).'Tag';
-        $class_name = '\\phpDocumentor\\Reflection\\DocBlock\\Tag\\' . $tag_name;
+        $class_name = 'phpDocumentor\\Reflection\\DocBlock\\Tag\\' . $tag_name;
 
         return (@class_exists($class_name))
             ? new $class_name($matches[1], isset($matches[2]) ? $matches[2] : '')
@@ -108,6 +111,21 @@ class Tag implements \Reflector
     {
         return $this->description;
     }
+    
+    /*
+     * Returns the parsed text of this description.
+     * 
+     * @return array An array of strings and tag objects, in the order they
+     * occur within the description.
+     */
+    public function getParsedDescription()
+    {
+        if (null === $this->parsedDescription) {
+            $description = new LongDescription($this->description);
+            $this->parsedDescription = $description->getParsedContents();
+        }
+        return $this->parsedDescription;
+    }
 
     /**
      * Set the tag line number

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

@@ -0,0 +1,68 @@
+<?php
+/**
+ * phpDocumentor
+ *
+ * PHP Version 5
+ *
+ * @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;
+
+use phpDocumentor\Reflection\DocBlock\Tag;
+
+/**
+ * Reflection class for an @author tag in a Docblock.
+ *
+ * @author   Mike van Riel <[email protected]>
+ * @license  http://www.opensource.org/licenses/mit-license.php MIT
+ * @link     http://phpdoc.org
+ */
+class AuthorTag extends Tag
+{
+    /** @var string The name of the author */
+    protected $name = '';
+    
+    /** @var string The email of the author */
+    protected $email = '';
+    
+    /**
+     * Parses a tag and populates the member variables.
+     *
+     * @param string $type    Name of the tag.
+     * @param string $content The contents of the given tag.
+     */
+    public function __construct($type, $content)
+    {
+        parent::__construct($type, $content);
+        if (preg_match('/^([^\<]*)(\<([^\>]*)\>)?$/', $content, $matches)) {
+            $this->name = trim($matches[1]);
+            if (isset($matches[3])) {
+                $this->email = trim($matches[3]);
+            }
+        }
+    }
+    
+    /**
+     * Gets the author's name.
+     * 
+     * @return string The author's name.
+     */
+    public function getAuthorName()
+    {
+        return $this->name;
+    }
+    
+    /**
+     * Gets the author's email.
+     * 
+     * @return string The author's email.
+     */
+    public function getAuthorEmail()
+    {
+        return $this->email;
+    }
+}

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

@@ -23,7 +23,7 @@ use phpDocumentor\Reflection\DocBlock\Tag;
 class ParamTag extends Tag
 {
     /** @var string */
-    protected $type = null;
+    protected $type = '';
 
     /**
      * @var string
@@ -33,7 +33,7 @@ class ParamTag extends Tag
     /**
      * 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 'param')
      * @param string $content Contents for this tag.
      */
     public function __construct($type, $content)
@@ -42,13 +42,13 @@ class ParamTag extends Tag
         $this->content = $content;
         $content = preg_split('/\s+/u', $content);
 
-        // if there is only 1, it is either a piece of content or a variable name
-        if (count($content) > 1) {
+        // if the first item that is encountered is not a variable; it is a type
+        if (isset($content[0]) && (strlen($content[0]) > 0) && ($content[0][0] !== '$')) {
             $this->type = array_shift($content);
         }
 
         // if the next item starts with a $ it must be the variable name
-        if ((strlen($content[0]) > 0) && ($content[0][0] == '$')) {
+        if (isset($content[0]) && (strlen($content[0]) > 0) && ($content[0][0] == '$')) {
             $this->variableName = array_shift($content);
         }
 
@@ -62,9 +62,13 @@ class ParamTag extends Tag
      */
     public function getTypes()
     {
-        $types = explode('|', $this->type);
-        array_walk($types, 'trim');
-        return $types;
+        $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();
     }
 
     /**
@@ -74,7 +78,7 @@ class ParamTag extends Tag
      */
     public function getType()
     {
-        return $this->type;
+        return implode('|', $this->getTypes());
     }
 
     /**

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

@@ -34,7 +34,8 @@ class ReturnTag extends ParamTag
     {
         $this->tag = $type;
         $this->content = $content;
-        $content = preg_split('/\s+/u', $content);
+
+        $content = preg_split('/[\ \t]+/u', $content, 2);
 
         // any output is considered a type
         $this->type = array_shift($content);
@@ -42,25 +43,4 @@ class ReturnTag extends ParamTag
         $this->description = implode(' ', $content);
     }
 
-    /**
-     * Returns the type of the variable.
-     *
-     * @return string
-     */
-    public function getTypes()
-    {
-        $types = explode('|', $this->type);
-        array_walk($types, 'trim');
-        return $types;
-    }
-
-    /**
-     * Returns the type of the variable.
-     *
-     * @return string
-     */
-    public function getType()
-    {
-        return $this->type;
-    }
 }

src/phpDocumentor/Reflection/DocBlock/Type/Collection.php

@@ -0,0 +1,248 @@
+<?php
+namespace phpDocumentor\Reflection\DocBlock\Type;
+
+class Collection extends \ArrayObject
+{
+    /** @var string Definition of the OR operator for types */
+    const OPERATOR_OR = '|';
+
+    /** @var string Definition of the ARRAY operator for types */
+    const OPERATOR_ARRAY = '[]';
+
+    /** @var string Definition of the NAMESPACE operator in PHP */
+    const OPERATOR_NAMESPACE = '\\';
+
+    /** @var string[] List of recognized keywords */
+    protected $keywords = array(
+        'string', 'int', 'integer', 'bool', 'boolean', 'float', 'double',
+        'object', 'mixed', 'array', 'resource', 'void', 'null',
+        'callback', 'callable', 'false', 'true', 'self', '$this', 'static'
+    );
+
+    /**
+     * Current namespace of the invoking location.
+     *
+     * This string is used to prepend to type with a relative location.
+     * May also be 'default' or 'global', in which case they are ignored.
+     *
+     * @var string
+     */
+    protected $namespace = '\\';
+
+    /**
+     * Associative array of alias => namespace pairs.
+     *
+     * @var string[]
+     */
+    protected $namespace_aliases = array();
+
+    /**
+     * Registers the namespace and aliases; uses that to add and expand the
+     * given types.
+     *
+     * @param string[]    $types             Array containing a list of types
+     *     to add to this container.
+     * @param string|null $namespace         The namespace where the types in
+     *     this container are relative to; used to expand any relative
+     *     namespaces.
+     * @param string[]    $namespace_aliases An array containing alias => FQNN
+     *     pairs that are used in the resolving process.
+     */
+    public function __construct(
+        array $types = array(), $namespace = null,
+        array $namespace_aliases = array()
+    ) {
+        // only set the namespace if overridden
+        if (is_string($namespace)) {
+            $this->setNamespace($namespace);
+        }
+        $this->namespace_aliases = $namespace_aliases;
+
+        foreach($types as $type) {
+            $this->add($type);
+        }
+    }
+
+    /**
+     * Returns the namespace name used to expand relative namespaces with.
+     *
+     * @return string
+     */
+    public function getNamespace()
+    {
+        return $this->namespace;
+    }
+
+    /**
+     * Sets the namespace which is used to resolve types with relative
+     * namespaces.
+     *
+     * Unless the name of the current namespace if default or global we make
+     * sure the namespace is succeeded with a '\'. This makes it clear for
+     * the processing functions that a leading slash is present.
+     *
+     * @param string $namespace
+     *
+     * @return void
+     */
+    public function setNamespace($namespace)
+    {
+        if ($namespace != 'default' && $namespace != 'global') {
+            $namespace = self::OPERATOR_NAMESPACE
+                . trim($namespace, self::OPERATOR_NAMESPACE)
+                . self::OPERATOR_NAMESPACE;
+        } else {
+            $namespace = '\\';
+        }
+
+        $this->namespace = $namespace;
+    }
+
+    /**
+     * Returns the list of namespace aliases used to expand the typed with.
+     *
+     * @return string[] An associative array of Alias => Fully Qualified
+     *     Namespace Names.
+     */
+    public function getNamespaceAliases()
+    {
+        return $this->namespace_aliases;
+    }
+
+    /**
+     * Sets the namespace aliases to expand the added types.
+     *
+     * @param string[] $namespace_aliases An associative array of Alias => Fully
+     *     Qualified Namespace Names.
+     *
+     * @return void
+     */
+    public function setNamespaceAliases($namespace_aliases)
+    {
+        $this->namespace_aliases = $namespace_aliases;
+    }
+
+    /**
+     * Adds a new type to the collection and expands it if it contains a
+     * relative namespace.
+     *
+     * If a class in the type contains a relative namespace than this collection
+     * will try to expand that into a FQCN.
+     *
+     * @param string $type A 'Type' as defined in the phpDocumentor
+     *     documentation.
+     *
+     * @throws \InvalidArgumentException if a non-string argument is passed.
+     *
+     * @see http://phpdoc.org/docs/latest/for-users/types.html for the
+     *     definition of a type.
+     *
+     * @return void
+     */
+    public function add($type)
+    {
+        if (!is_string($type)) {
+            throw new \InvalidArgumentException(
+                'A type should be represented by a string, received: '
+                .var_export($type, true)
+            );
+        }
+
+        // separate the type by the OR operator
+        $type_parts = explode(self::OPERATOR_OR, $type);
+        foreach($type_parts as $part) {
+            $expanded_type = $this->expand($part);
+            if ($expanded_type) {
+                $this[] = $expanded_type;
+            }
+        }
+    }
+
+    /**
+     * Analyzes the given type and returns the FQCN variant.
+     *
+     * When a type is provided this method checks whether it is not a keyword or
+     * Fully Qualified Class Name. If so it will use the given namespace and
+     * aliases to expand the type to a FQCN representation.
+     *
+     * This method only works as expected if the namespace and aliases are set;
+     * no dynamic reflection is being performed here.
+     *
+     * @uses getNamespace to determine with what to prefix the type name.
+     * @uses getNamespaceAliases to check whether the first part of the relative
+     *     type name should not be replaced with another namespace.
+     *
+     * @param string $type The relative or absolute type.
+     *
+     * @return string
+     */
+    protected function expand($type)
+    {
+        $type = trim($type);
+        if (!$type) {
+            return '';
+        }
+
+        if ($this->isTypeAnArray($type)) {
+            return $this->expand(substr($type, 0, -2)).self::OPERATOR_ARRAY;
+        }
+
+        if ($this->isRelativeType($type) && !$this->isTypeAKeyword($type)) {
+            $type_parts = explode(self::OPERATOR_NAMESPACE, $type);
+
+            // if the first segment is not an alias; prepend namespace name and
+            // return
+            if (!isset($this->namespace_aliases[$type_parts[0]])) {
+                return $this->getNamespace() . $type;
+            }
+
+            $type_parts[0] = $this->namespace_aliases[$type_parts[0]];
+            $type = implode(self::OPERATOR_NAMESPACE, $type_parts);
+        }
+
+        return $type;
+    }
+
+    /**
+     * Detects whether the given type represents an array.
+     *
+     * @param string $type A relative or absolute type as defined in the
+     *     phpDocumentor documentation.
+     *
+     * @return bool
+     */
+    protected function isTypeAnArray($type)
+    {
+        return (substr($type, -2) == self::OPERATOR_ARRAY);
+    }
+
+    /**
+     * Detects whether the given type represents a PHPDoc keyword.
+     *
+     * @param string $type A relative or absolute type as defined in the
+     *     phpDocumentor documentation.
+     *
+     * @return bool
+     */
+    protected function isTypeAKeyword($type)
+    {
+        return in_array(strtolower($type), $this->keywords);
+    }
+
+    /**
+     * Detects whether the given type represents a relative or absolute path.
+     *
+     * This method will detect keywords as being absolute; even though they are
+     * not preceeded by a namespace separator.
+     *
+     * @param string $type A relative or absolute type as defined in the
+     *     phpDocumentor documentation.
+     *
+     * @return bool
+     */
+    protected function isRelativeType($type)
+    {
+        return ($type[0] !== self::OPERATOR_NAMESPACE)
+            || $this->isTypeAKeyword($type);
+    }
+}

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

@@ -8,10 +8,6 @@
 
 namespace phpDocumentor\Reflection\DocBlock\Tag;
 
-require_once __DIR__.'/../../../../../src/phpDocumentor/Reflection/DocBlock/Tag.php';
-require_once __DIR__.'/../../../../../src/phpDocumentor/Reflection/DocBlock/Tag/SeeTag.php';
-require_once __DIR__.'/../../../../../src/phpDocumentor/Reflection/DocBlock/Tag/CoversTag.php';
-
 /**
  * Test class for phpDocumentor_Reflection_DocBlock_Tag_Covers
  *

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

@@ -8,8 +8,6 @@
 
 namespace phpDocumentor\Reflection\DocBlock\Tag;
 
-require_once __DIR__ . '/../../../../../src/phpDocumentor/Reflection/DocBlock/Tag/LinkTag.php';
-
 /**
  * Test class for \phpDocumentor\Reflection\DocBlock\Tag\LinkTag
  *

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

@@ -8,9 +8,6 @@
 
 namespace phpDocumentor\Reflection\DocBlock\Tag;
 
-require_once __DIR__ . '/../../../../../src/phpDocumentor/Reflection/DocBlock/Tag/ParamTag.php';
-require_once __DIR__ . '/../../../../../src/phpDocumentor/Reflection/DocBlock/Tag/MethodTag.php';
-
 /**
  * Test class for \phpDocumentor\Reflection\DocBlock\Tag\MethodTag
  *

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

@@ -0,0 +1,67 @@
+<?php
+/**
+ * phpDocumentor Param tag test.
+ *
+ * @author    Mike van Riel <[email protected]>
+ * @copyright Copyright (c) 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com)
+ */
+
+namespace phpDocumentor\Reflection\DocBlock\Tag;
+
+/**
+ * Test class for phpDocumentor_Reflection_DocBlock_Param.
+ *
+ * @author     Mike van Riel <[email protected]>
+ * @copyright  Copyright (c) 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com)
+ */
+class ParamTagTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * Test that the \phpDocumentor\Reflection\DocBlock\Tag\ParamTag can
+     * understand the param DocBlock.
+     *
+     * @param string $type
+     * @param string $content
+     * @param string $extracted_type
+     * @param string $extracted_variable_name
+     * @param string $extracted_description
+     *
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag\ParamTag::__construct
+     *
+     * @dataProvider provideDataForConstructor
+     *
+     * @return void
+     */
+    public function testConstructorParsesInputsIntoCorrectFields(
+        $type, $content, $extracted_type, $extracted_variable_name,
+        $extracted_description
+    ) {
+        $tag = new ParamTag($type, $content);
+
+        $this->assertEquals($extracted_type,          $tag->getTypes());
+        $this->assertEquals($extracted_variable_name, $tag->getVariableName());
+        $this->assertEquals($extracted_description,   $tag->getDescription());
+    }
+
+    /**
+     * Data provider for testConstructorParsesInputsIntoCorrectFields()
+     *
+     * @return array
+     */
+    public function provideDataForConstructor()
+    {
+        return array(
+            array('param', 'int', array('int'), '', ''),
+            array('param', '$bob', array(), '$bob', ''),
+            array(
+                'param', 'int Number of bobs', array('int'), '',
+                'Number of bobs'
+            ),
+            array('param', 'int $bob', array('int'), '$bob', ''),
+            array(
+                'param', 'int $bob Number of bobs', array('int'), '$bob',
+                'Number of bobs'
+            ),
+        );
+    }
+}

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

@@ -0,0 +1,55 @@
+<?php
+/**
+ * phpDocumentor Return tag test.
+ *
+ * @author    Mike van Riel <[email protected]>
+ * @copyright Copyright (c) 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com)
+ */
+
+namespace phpDocumentor\Reflection\DocBlock\Tag;
+
+/**
+ * Test class for phpDocumentor_Reflection_DocBlock_ReturnTag.
+ *
+ * @author     Mike van Riel <[email protected]>
+ * @copyright  Copyright (c) 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com)
+ */
+class ReturnTagTest extends ParamTagTest
+{
+    /**
+     * Test that the \phpDocumentor\Reflection\DocBlock\Tag\ReturnTag can
+     * understand the Return DocBlock.
+     *
+     * @param string $content
+     * @param string $extracted_type
+     * @param string $extracted_description
+     *
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag\ReturnTag::__construct
+     *
+     * @dataProvider provideDataForConstructor
+     *
+     * @return void
+     */
+    public function testConstructorParsesInputsIntoCorrectFields(
+        $content, $extracted_type, $extracted_description
+    ) {
+        $tag = new ReturnTag('return', $content);
+
+        $this->assertEquals($extracted_type,          $tag->getTypes());
+        $this->assertEquals($extracted_description,   $tag->getDescription());
+    }
+
+    /**
+     * Data provider for testConstructorParsesInputsIntoCorrectFields()
+     *
+     * @return array
+     */
+    public function provideDataForConstructor()
+    {
+        return array(
+            array('', array(), ''),
+            array('int', array('int'), ''),
+            array('int Number of Bobs', array('int'), 'Number of Bobs'),
+        );
+    }
+}

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

@@ -8,8 +8,6 @@
 
 namespace phpDocumentor\Reflection\DocBlock\Tag;
 
-require_once __DIR__ . '/../../../../../src/phpDocumentor/Reflection/DocBlock/Tag/SeeTag.php';
-
 /**
  * Test class for phpDocumentor_Reflection_DocBlock_Tag_See
  *

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

@@ -8,8 +8,6 @@
 
 namespace phpDocumentor\Reflection\DocBlock\Tag;
 
-require_once __DIR__ . '/../../../../../src/phpDocumentor/Reflection/DocBlock/Tag/UsesTag.php';
-
 /**
  * Test class for phpDocumentor_Reflection_DocBlock_Tag_Uses
  *

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

@@ -8,8 +8,6 @@
 
 namespace phpDocumentor\Reflection\DocBlock\Tag;
 
-require_once __DIR__ . '/../../../../../src/phpDocumentor/Reflection/DocBlock/Tag/VarTag.php';
-
 /**
  * Test class for phpDocumentor_Reflection_DocBlock_Tag_Link
  *

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

@@ -0,0 +1,194 @@
+<?php
+namespace phpDocumentor\Reflection\DocBlock\Type;
+
+/**
+ * Test class for phpDocumentor_Reflection_DocBlock
+ * @covers phpDocumentor\Reflection\DocBlock\Type\Collection
+ */
+class CollectionTest extends \PHPUnit_Framework_TestCase
+{
+    /**
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::__construct
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::getNamespace
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::getNamespaceAliases
+     */
+    public function testConstruct()
+    {
+        $collection = new Collection();
+        $this->assertCount(0, $collection);
+        $this->assertEquals('\\', $collection->getNamespace());
+        $this->assertCount(0, $collection->getNamespaceAliases());
+    }
+
+    /**
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::__construct
+     */
+    public function testConstructWithTypes()
+    {
+        $collection = new Collection(array('integer', 'string'));
+        $this->assertCount(2, $collection);
+    }
+
+    /**
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::__construct
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::getNamespace
+     */
+    public function testConstructWithNamespace()
+    {
+        $collection = new Collection(array(), '\My\Space');
+        $this->assertEquals('\My\Space\\', $collection->getNamespace());
+
+        $collection = new Collection(array(), 'My\Space');
+        $this->assertEquals('\My\Space\\', $collection->getNamespace());
+
+        $collection = new Collection(array(), null);
+        $this->assertEquals('\\', $collection->getNamespace());
+    }
+
+    /**
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::__construct
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::getNamespaceAliases
+     */
+    public function testConstructWithNamespaceAliases()
+    {
+        $fixture = array('a' => 'b');
+        $collection = new Collection(array(), null, $fixture);
+        $this->assertEquals($fixture, $collection->getNamespaceAliases());
+    }
+
+    /**
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::setNamespace
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::getNamespace
+     */
+    public function testSetAndGetNamespace()
+    {
+        $collection = new Collection();
+        $this->assertEquals('\\', $collection->getNamespace());
+
+        $collection->setNamespace('My');
+        $this->assertEquals('\My\\', $collection->getNamespace());
+
+        $collection->setNamespace('\My');
+        $this->assertEquals('\My\\', $collection->getNamespace());
+
+        $collection->setNamespace('\My\\');
+        $this->assertEquals('\My\\', $collection->getNamespace());
+    }
+
+    /**
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::setNamespaceAliases
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::getNamespaceAliases
+     */
+    public function testSetAndGetNamespaceAliases()
+    {
+        $collection = new Collection();
+        $this->assertEmpty($collection->getNamespaceAliases());
+
+        $collection->setNamespaceAliases(array('My'));
+        $this->assertEquals(array('My'), $collection->getNamespaceAliases());
+    }
+
+    /**
+     * @param $fixture
+     * @param $expected
+     *
+     * @dataProvider provideTypesToExpand
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::add
+     */
+    public function testAdd($fixture, $expected)
+    {
+        $collection = new Collection();
+        $collection->setNamespace('\My\Space');
+        $collection->setNamespaceAliases(array('Alias' => '\My\Space\Aliasing'));
+        $collection->add($fixture);
+
+        $this->assertSame($expected, $collection->getArrayCopy());
+    }
+
+    /**
+     * @param $fixture
+     * @param $expected
+     *
+     * @dataProvider provideTypesToExpandWithoutNamespace
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::add
+     */
+    public function testAddWithoutNamespace($fixture, $expected)
+    {
+        $collection = new Collection();
+        $collection->setNamespaceAliases(array('Alias' => '\My\Space\Aliasing'));
+        $collection->add($fixture);
+
+        $this->assertSame($expected, $collection->getArrayCopy());
+    }
+
+    /**
+     * @covers phpDocumentor\Reflection\DocBlock\Type\Collection::add
+     * @expectedException InvalidArgumentException
+     */
+    public function testAddWithInvalidArgument()
+    {
+        $collection = new Collection();
+        $collection->add(array());
+    }
+
+    /**
+     * Returns the types and their expected values to test the retrieval of
+     * types.
+     *
+     * @param string $method Name of the method consuming this data provider.
+     * @param string $namespace Name of the namespace to user as basis.
+     *
+     * @return string[]
+     */
+    public function provideTypesToExpand($method, $namespace = '\My\Space\\')
+    {
+        return array(
+            array('', array()),
+            array(' ', array()),
+            array('int', array('int')),
+            array('int ', array('int')),
+            array('string', array('string')),
+            array('DocBlock', array($namespace.'DocBlock')),
+            array('DocBlock[]', array($namespace.'DocBlock[]')),
+            array(' DocBlock ', array($namespace.'DocBlock')),
+            array('\My\Space\DocBlock', array('\My\Space\DocBlock')),
+            array('Alias\DocBlock', array('\My\Space\Aliasing\DocBlock')),
+            array(
+                'DocBlock|Tag',
+                array($namespace .'DocBlock', $namespace .'Tag')
+            ),
+            array(
+                'DocBlock|null',
+                array($namespace.'DocBlock', 'null')
+            ),
+            array(
+                '\My\Space\DocBlock|Tag',
+                array('\My\Space\DocBlock', $namespace.'Tag')
+            ),
+            array(
+                'DocBlock[]|null',
+                array($namespace.'DocBlock[]', 'null')
+            ),
+            array(
+                'DocBlock[]|int[]',
+                array($namespace.'DocBlock[]', 'int[]')
+            ),
+        );
+    }
+
+    /**
+     * Returns the types and their expected values to test the retrieval of
+     * types when no namespace is available.
+     *
+     * @param string $method Name of the method consuming this data provider.
+     * @param string $namespace Name of the namespace to user as basis.
+     *
+     * @return string[]
+     */
+    public function provideTypesToExpandWithoutNamespace($method)
+    {
+        return $this->provideTypesToExpand($method, '\\');
+    }
+
+}
+

tests/phpDocumentor/Reflection/DocBlockTest.php

@@ -10,9 +10,6 @@
 
 namespace phpDocumentor\Reflection;
 
-require_once __DIR__.'/../../../src/phpDocumentor/Reflection/DocBlock.php';
-require_once __DIR__.'/../../../src/phpDocumentor/Reflection/DocBlock/LongDescription.php';
-
 /**
  * Test class for phpDocumentor_Reflection_DocBlock
  *
@@ -38,10 +35,110 @@ DOCBLOCK;
             'This is a short description.', $object->getShortDescription()
         );
         $this->assertEquals(
-            'This is a long description.', $object->getLongDescription()->getContents()
+            'This is a long description.',
+            $object->getLongDescription()->getContents()
         );
         $this->assertEquals(2, count($object->getTags()));
         $this->assertTrue($object->hasTag('see'));
         $this->assertTrue($object->hasTag('return'));
     }
+
+    public function testDotSeperation()
+    {
+        $fixture = <<<DOCBLOCK
+/**
+ * This is a short description. This is a long description.
+ * This is a continuation of the long description.
+ */
+DOCBLOCK;
+        $object = new DocBlock($fixture);
+        $this->assertEquals(
+            'This is a short description.', $object->getShortDescription()
+        );
+        $this->assertEquals(
+            "This is a long description.\nThis is a continuation of the long "
+            ."description.", $object->getLongDescription()->getContents()
+        );
+    }
+
+    /**
+     * Tests whether a type is expanded with the given namespace and that a
+     * keyword is not expanded.
+     *
+     * @covers \phpDocumentor\Reflection\DocBlock::expandType()
+     *
+     * @return void
+     */
+    public function testExpandTypeUsingNamespace()
+    {
+        $docblock = new DocBlock('', '\My\Namespace');
+        $this->assertEquals('\My\Namespace\Mine', $docblock->expandType('Mine'));
+    }
+
+    /**
+     * Tests whether a type is expanded when no namespace is given.
+     *
+     * @covers \phpDocumentor\Reflection\DocBlock::expandType()
+     *
+     * @return void
+     */
+    public function testExpandTypeWithoutNamespace()
+    {
+        $docblock = new DocBlock('');
+        $this->assertEquals('\Mine', $docblock->expandType('Mine'));
+    }
+
+    /**
+     * Tests whether a type is expanded with the given namespace when an alias
+     * is provided.
+     *
+     * @covers \phpDocumentor\Reflection\DocBlock::expandType()
+     *
+     * @return void
+     */
+    public function testExpandTypeUsingNamespaceAlias()
+    {
+        $docblock = new DocBlock(
+            '', '\My\Namespace', array('Alias' => '\My\Namespace\Alias')
+        );
+
+        // first try a normal resolution without alias
+        $this->assertEquals(
+            '\My\Namespace\Al', $docblock->expandType('Al')
+        );
+
+        // 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.
+     *
+     * @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)
+    {
+        $docblock = new DocBlock('', '\My\Namespace');
+        $this->assertEquals($keyword, $docblock->expandType($keyword));
+    }
+
+    public function getNonExpandableKeywordsForExpandType()
+    {
+        return array(
+            array('string'), array('int'), array('integer'), array('bool'),
+            array('boolean'), array('float'), array('double'), array('object'),
+            array('mixed'), array('array'), array('resource'), array('void'),
+            array('null'), array('callback'), array('false'), array('true')
+        );
+    }
 }
+