Added support for namespaced tags;

Simplified @see and @link parsing;
Added comments to the regexes of @method, @example and @source;
Added a test case for what 2812eac intended to fix.

Author: boenrobot

src/phpDocumentor/Reflection/DocBlock/Tag.php

@@ -113,16 +113,21 @@ final public static function createInstance(
             );
         }
 
+        $handler = __CLASS__;
         if (isset(self::$tagHandlerMappings[$matches[1]])) {
             $handler = self::$tagHandlerMappings[$matches[1]];
-            return new $handler(
-                $matches[1],
-                isset($matches[2]) ? $matches[2] : '',
-                $docblock,
-                $location
+        } elseif (isset($docblock)) {
+            $tagName = (string)new Type\Collection(
+                array($matches[1]),
+                $docblock->getContext()
             );
+
+            if (isset(self::$tagHandlerMappings[$tagName])) {
+                $handler = self::$tagHandlerMappings[$tagName];
+            }
         }
-        return new self(
+
+        return new $handler(
             $matches[1],
             isset($matches[2]) ? $matches[2] : '',
             $docblock,
@@ -136,7 +141,9 @@ final public static function createInstance(
      * 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      $tag     Name of tag to regiser a handler for. When
+     *     registering a namespaced tag, the full name, along with a prefixing
+     *     slash MUST be provided.
      * @param string|null $handler FQCN of handler. Specifing NULL removes the
      *     handler for the specified tag, if any.
      * 
@@ -154,6 +161,7 @@ final public static function registerTagHandler($tag, $handler)
         if ('' !== $tag
             && class_exists($handler, true)
             && is_subclass_of($handler, __CLASS__)
+            && !strpos($tag, '\\') //Accept no slash, and 1st slash at offset 0.
         ) {
             self::$tagHandlerMappings[$tag] = $handler;
             return true;

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

@@ -43,7 +43,17 @@ public function __construct(
     ) {
         Tag::__construct($type, $content, $docblock, $location);
         if (preg_match(
-            '/^(?:\"([^\"]+)\"|(\S+))(?:\s+(.*))?$/su',
+            '/^
+                (?:
+                    # File path in quotes
+                    \"([^\"]+)\"
+                    |
+                    # File URI
+                    (\S+)
+                )
+                # Remaining content (parsed by SourceTag)
+                (?:\s+(.*))?
+            $/sux',
             $this->description,
             $matches
         )) {

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

@@ -42,17 +42,12 @@ public function __construct(
         Location $location = null
     ) {
         parent::__construct($type, $content, $docblock, $location);
-        $pieces = explode(' ', $this->description);
+        $content = preg_split('/\s+/u', $this->description, 2);
 
-        if (count($pieces) > 1) {
-            $this->link = array_shift($pieces);
-            $this->description = implode(' ', $pieces);
-        } else {
-            $this->link = $content;
-            $this->description = $content;
-        }
+        // any output is considered a type
+        $this->link = $content[0];
 
-        $this->content = $content;
+        $this->description = isset($content[1]) ? $content[1] : $content[0];
     }
 
     /**

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

@@ -57,8 +57,24 @@ public function __construct(
         //    until a ) and whitespace : as method name with signature
         // 5. any remaining text : as description
         if (preg_match(
-            '/^[\s]*(?:([\w\|_\\\\]+)[\s]+)?(?:[\w_]+\(\)[\s]+)?([\w\|_\\\\]+)'
-            .'\(([^\)]*)\)[\s]*(.*)/u',
+            '/^
+                # Return type
+                (?:
+                    ([\w\|_\\\\]+)
+                    \s+
+                )?
+                # Legacy method name (not captured)
+                (?:
+                    [\w_]+\(\)\s+
+                )?
+                # Method name
+                ([\w\|_\\\\]+)
+                # Arguments
+                \(([^\)]*)\)
+                \s*
+                # Description
+                (.*)
+            $/sux',
             $this->description,
             $matches
         )) {

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

@@ -42,12 +42,12 @@ public function __construct(
         Location $location = null
     ) {
         parent::__construct($type, $content, $docblock, $location);
-        $content = preg_split('/\s+/u', $content);
+        $content = preg_split('/\s+/u', $this->description, 2);
 
         // any output is considered a type
-        $this->refers = array_shift($content);
+        $this->refers = $content[0];
 
-        $this->description = implode(' ', $content);
+        $this->description = isset($content[1]) ? $content[1] : '';
     }
 
     /**

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

@@ -51,7 +51,18 @@ public function __construct(
     ) {
         parent::__construct($type, $content, $docblock, $location);
         if (preg_match(
-            '/^([1-9]\d*)\s*(?:([1-9]\d*)\s+)?(.*)$/su',
+            '/^
+                # Starting line
+                ([1-9]\d*)
+                \s*
+                # Number of lines
+                (?:
+                    ((?1))
+                    \s+
+                )?
+                # Description
+                (.*)
+            $/sux',
             $this->description,
             $matches
         )) {

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

@@ -92,6 +92,13 @@ public function provideDataForConstructor()
                 'int',
                 array('int'),
                 "Number of Bobs"
+            ),
+            array(
+                'return',
+                "int\nNumber of Bobs",
+                'int',
+                array('int'),
+                "Number of Bobs"
             )
         );
     }

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

@@ -90,6 +90,13 @@ public function provideDataForConstructor()
                 'int',
                 array('int'),
                 "Number of Bobs"
+            ),
+            array(
+                'throws',
+                "int\nNumber of Bobs",
+                'int',
+                array('int'),
+                "Number of Bobs"
             )
         );
     }