From bae65d2afea720a04a40816696fc99fa6cb229c8 Mon Sep 17 00:00:00 2001
From: Vasil Rangelov <boen.robot@gmail.com>
Date: Sun, 11 Nov 2012 15:20:59 +0200
Subject: [PATCH] Minor syntax and doc fixes at Tag::registerTagHandler();
 Split the "testTagHandlerRegistration" test into several new ones, with
 appropriate @covers annotations added; Although not required for single
 liners, class names at the built in tag handlers map are indented on a
 separate line for readability.

---
 src/phpDocumentor/Reflection/DocBlock/Tag.php | 48 +++++++----
 .../Reflection/DocBlock/TagTest.php           | 84 +++++++++++++++++--
 2 files changed, 108 insertions(+), 24 deletions(-)

diff --git a/src/phpDocumentor/Reflection/DocBlock/Tag.php b/src/phpDocumentor/Reflection/DocBlock/Tag.php
index 4496904..1c8be4a 100644
--- a/src/phpDocumentor/Reflection/DocBlock/Tag.php
+++ b/src/phpDocumentor/Reflection/DocBlock/Tag.php
@@ -45,22 +45,34 @@ class Tag implements \Reflector
      *     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',
+        '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'
+            => '\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'
+        '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'
     );
 
     /**
@@ -100,8 +112,8 @@ class Tag implements \Reflector
      * 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 $handler FQCN of handler. Specifing NULL removes the
+     * @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.
@@ -109,19 +121,21 @@ class Tag implements \Reflector
     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__)
+            && is_subclass_of($handler, __CLASS__)
         ) {
             self::$tagHandlerMappings[$tag] = $handler;
             return true;
-        } else {
-            return false;
         }
+
+        return false;
     }
 
     /**
diff --git a/tests/phpDocumentor/Reflection/DocBlock/TagTest.php b/tests/phpDocumentor/Reflection/DocBlock/TagTest.php
index 9b5ee11..cd77acf 100644
--- a/tests/phpDocumentor/Reflection/DocBlock/TagTest.php
+++ b/tests/phpDocumentor/Reflection/DocBlock/TagTest.php
@@ -33,6 +33,11 @@ class TagTest extends \PHPUnit_Framework_TestCase
         Tag::createInstance('Invalid tag line');
     }
 
+    /**
+     * @covers \phpDocumentor\Reflection\DocBlock\Tag::registerTagHandler
+     * 
+     * @return void
+     */
     public function testTagHandlerUnregistration()
     {
         $currentHandler = __NAMESPACE__ . '\Tag\VarTag';
@@ -61,7 +66,12 @@ class TagTest extends \PHPUnit_Framework_TestCase
         Tag::registerTagHandler('var', $currentHandler);
     }
 
-    public function testTagHandlerRegistration()
+    /**
+     * @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.');
@@ -77,18 +87,14 @@ class TagTest extends \PHPUnit_Framework_TestCase
             $tagPreUnreg
         );
 
-        require 'data:text/plain;base64,'. base64_encode(<<<TAG_HANDLER
+        require 'data:text/plain;base64,'. base64_encode(
+<<<TAG_HANDLER
 <?php
     class MyVarHandler extends \phpDocumentor\Reflection\DocBlock\Tag {}
 TAG_HANDLER
         );
 
-        
-        $this->assertFalse(Tag::registerTagHandler('var', 'Non existent'));
         $this->assertTrue(Tag::registerTagHandler('var', '\MyVarHandler'));
-        $this->assertFalse(
-            Tag::registerTagHandler('var', __NAMESPACE__ . '\TagTest')
-        );
 
         $tagPostUnreg = Tag::createInstance('@var mixed');
         $this->assertNotInstanceOf(
@@ -107,6 +113,70 @@ TAG_HANDLER
         $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.