Write tests for DescriptionFactory and adjust components for minor bugs that were found

tests/unit/DocBlock/DescriptionFactoryTest.php

@@ -13,16 +13,138 @@
 namespace phpDocumentor\Reflection\DocBlock;
 
 use Mockery as m;
+use phpDocumentor\Reflection\DocBlock\Tags\Link;
+use phpDocumentor\Reflection\Types\Context;
+
 /**
  * @coversDefaultClass \phpDocumentor\Reflection\DocBlock\DescriptionFactory
+ * @covers ::<private>
  */
 class DescriptionFactoryTest extends \PHPUnit_Framework_TestCase
 {
     /**
      * @covers ::__construct
+     * @covers ::create
+     * @uses         phpDocumentor\Reflection\DocBlock\Description
+     * @dataProvider provideSimpleExampleDescriptions
      */
-    public function testDescriptionCanRenderUsingABodyWithPlaceholdersAndTags()
+    public function testDescriptionCanParseASimpleString($contents)
     {
+        $tagFactory = m::mock(TagFactory::class);
+        $tagFactory->shouldReceive('create')->never();
+
+        $factory     = new DescriptionFactory($tagFactory);
+        $description = $factory->create($contents, new Context(''));
+
+        $this->assertSame($contents, $description->render());
+    }
+
+    /**
+     * @covers ::__construct
+     * @covers ::create
+     * @uses         phpDocumentor\Reflection\DocBlock\Description
+     * @dataProvider provideEscapeSequences
+     */
+    public function testEscapeSequences($contents, $expected)
+    {
+        $tagFactory = m::mock(TagFactory::class);
+        $tagFactory->shouldReceive('create')->never();
+
+        $factory     = new DescriptionFactory($tagFactory);
+        $description = $factory->create($contents, new Context(''));
+
+        $this->assertSame($expected, $description->render());
+    }
+
+    /**
+     * @covers ::__construct
+     * @covers ::create
+     * @uses   phpDocumentor\Reflection\DocBlock\Description
+     * @uses   phpDocumentor\Reflection\DocBlock\Tags\Link
+     * @uses   phpDocumentor\Reflection\DocBlock\Tags\BaseTag
+     * @uses   phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
+     * @uses   phpDocumentor\Reflection\Types\Context
+     */
+    public function testDescriptionCanParseAStringWithInlineTag()
+    {
+        $contents   = 'This is text for a {@link http://phpdoc.org/ description} that uses an inline tag.';
+        $context    = new Context('');
+        $tagFactory = m::mock(TagFactory::class);
+        $tagFactory->shouldReceive('create')
+            ->once()
+            ->with('@link http://phpdoc.org/ description', $context)
+            ->andReturn(new Link('http://phpdoc.org/', new Description('description')))
+        ;
+
+        $factory     = new DescriptionFactory($tagFactory);
+        $description = $factory->create($contents, $context);
+
+        $this->assertSame($contents, $description->render());
+    }
+
+    /**
+     * @covers ::__construct
+     * @covers ::create
+     * @uses   phpDocumentor\Reflection\DocBlock\Description
+     * @uses   phpDocumentor\Reflection\DocBlock\Tags\Link
+     * @uses   phpDocumentor\Reflection\DocBlock\Tags\BaseTag
+     * @uses   phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
+     * @uses   phpDocumentor\Reflection\Types\Context
+     */
+    public function testDescriptionCanParseAStringStartingWithInlineTag()
+    {
+        $contents   = '{@link http://phpdoc.org/ This} is text for a description that starts with an inline tag.';
+        $context    = new Context('');
+        $tagFactory = m::mock(TagFactory::class);
+        $tagFactory->shouldReceive('create')
+            ->once()
+            ->with('@link http://phpdoc.org/ This', $context)
+            ->andReturn(new Link('http://phpdoc.org/', new Description('This')))
+        ;
+
+        $factory     = new DescriptionFactory($tagFactory);
+        $description = $factory->create($contents, $context);
+
+        $this->assertSame($contents, $description->render());
+    }
+
+    /**
+     * @covers ::__construct
+     * @covers ::create
+     * @uses   phpDocumentor\Reflection\DocBlock\Description
+     */
+    public function testIfSuperfluousStartingSpacesAreRemoved()
+    {
+        $factory         = new DescriptionFactory(m::mock(TagFactory::class));
+        $descriptionText = <<<DESCRIPTION
+This is a multiline
+  description that you commonly
+  see with tags.
+
+      It does have a code sample
+
+  All spaces superfluous spaces on the
+  second and later lines should be
+  removed but the code sample should
+  still be indented.
+DESCRIPTION;
+
+        $expectedDescription = <<<DESCRIPTION
+This is a multiline
+description that you commonly
+see with tags.
+
+    It does have a code sample
+
+All spaces superfluous spaces on the
+second and later lines should be
+removed but the code sample should
+still be indented.
+DESCRIPTION;
+
+        $description = $factory->create($descriptionText, new Context(''));
+
+        $this->assertSame($expectedDescription, $description->render());
     }
 
     /**
@@ -30,21 +152,21 @@ class DescriptionFactoryTest extends \PHPUnit_Framework_TestCase
      *
      * @return string[][]
      */
-    public function provideExampleDescriptions()
+    public function provideSimpleExampleDescriptions()
     {
         return [
             ['This is text for a description.'],
-            ['This is text for a {@link http://phpdoc.org/ description} that uses an inline tag.'],
-            ['{@link http://phpdoc.org/ This} is text for a description that starts with an inline tag.'],
-            [
-                'This is text for a description with {@internal inline tag with {@link http://phpdoc.org another '
-                . 'inline tag} in it}.'
-            ],
             ['This is text for a description containing { that is literal.'],
-            ['This is text for a description containing {@internal inline tag that has { that is literal}.'],
-            ['This is text for a description with {} that is not a tag.'],
-            ['This is text for a description with {@internal inline tag with {} that is not an inline tag}.'],
-            ['This is text for a description with an {@internal inline tag with literal {{@}link{} in it}.']
+            ['This is text for a description containing } that is literal.'],
+            ['This is text for a description with {just a text} that is not a tag.'],
+        ];
+    }
+
+    public function provideEscapeSequences()
+    {
+        return [
+            ['This is text for a description with a {@}.', 'This is text for a description with a @.'],
+            ['This is text for a description with a {}.', 'This is text for a description with a }.'],
         ];
     }
 }

tests/unit/DocBlock/Tags/AuthorTest.php

@@ -36,12 +36,13 @@ class AuthorTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Author::__toString
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new Author('Mike van Riel', '[email protected]');
 
-        $this->assertSame('Mike van Riel<[email protected]>', $fixture->render());
+        $this->assertSame('@author Mike van Riel<[email protected]>', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/CoversTest.php

@@ -43,12 +43,13 @@ class CoversTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new Covers(new Fqsen('\DateTime'), new Description('Description'));
 
-        $this->assertSame('\DateTime Description', $fixture->render());
+        $this->assertSame('@covers \DateTime Description', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/DeprecatedTest.php

@@ -41,12 +41,13 @@ class DeprecatedTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new Deprecated('1.0', new Description('Description'));
 
-        $this->assertSame('1.0 Description', $fixture->render());
+        $this->assertSame('@deprecated 1.0 Description', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/GenericTest.php

@@ -89,7 +89,7 @@ class GenericTest extends \PHPUnit_Framework_TestCase
     {
         $fixture = new Generic('generic', new Description('Description'));
 
-        $this->assertSame('@generic Description', (string)$fixture);
+        $this->assertSame('Description', (string)$fixture);
     }
 
     /**
@@ -111,7 +111,7 @@ class GenericTest extends \PHPUnit_Framework_TestCase
 
         $fixture = Generic::create('My Description', 'generic', $descriptionFactory, $context);
 
-        $this->assertSame('@generic My Description', (string)$fixture);
+        $this->assertSame('My Description', (string)$fixture);
         $this->assertSame($generics, $fixture->getName());
         $this->assertSame($description, $fixture->getDescription());
     }

tests/unit/DocBlock/Tags/LinkTest.php

@@ -41,12 +41,13 @@ class LinkTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new Link('http://this.is.my/link', new Description('Description'));
 
-        $this->assertSame('http://this.is.my/link Description', $fixture->render());
+        $this->assertSame('@link http://this.is.my/link Description', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/MethodTest.php

@@ -47,6 +47,7 @@ class MethodTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
@@ -57,7 +58,7 @@ class MethodTest extends \PHPUnit_Framework_TestCase
         $fixture = new Method('myMethod', $arguments, new Void(), true, new Description('My Description'));
 
         $this->assertSame(
-            'static void myMethod(string $argument1, object $argument2) My Description',
+            '@method static void myMethod(string $argument1, object $argument2) My Description',
             $fixture->render()
         );
     }

tests/unit/DocBlock/Tags/ParamTest.php

@@ -44,20 +44,21 @@ class ParamTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new Param('myParameter', new String_(), true, new Description('Description'));
-        $this->assertSame('string ...$myParameter Description', $fixture->render());
+        $this->assertSame('@param string ...$myParameter Description', $fixture->render());
 
         $fixture = new Param('myParameter', new String_(), false, new Description('Description'));
-        $this->assertSame('string $myParameter Description', $fixture->render());
+        $this->assertSame('@param string $myParameter Description', $fixture->render());
 
         $fixture = new Param('myParameter', null, false, new Description('Description'));
-        $this->assertSame('$myParameter Description', $fixture->render());
+        $this->assertSame('@param $myParameter Description', $fixture->render());
 
         $fixture = new Param('myParameter');
-        $this->assertSame('$myParameter', $fixture->render());
+        $this->assertSame('@param $myParameter', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/PropertyReadTest.php

@@ -43,17 +43,18 @@ class PropertyReadTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new PropertyRead('myProperty', new String_(), new Description('Description'));
-        $this->assertSame('string $myProperty Description', $fixture->render());
+        $this->assertSame('@property-read string $myProperty Description', $fixture->render());
 
         $fixture = new PropertyRead('myProperty', null, new Description('Description'));
-        $this->assertSame('$myProperty Description', $fixture->render());
+        $this->assertSame('@property-read $myProperty Description', $fixture->render());
 
         $fixture = new PropertyRead('myProperty');
-        $this->assertSame('$myProperty', $fixture->render());
+        $this->assertSame('@property-read $myProperty', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/PropertyTest.php

@@ -43,17 +43,18 @@ class PropertyTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new Property('myProperty', new String_(), new Description('Description'));
-        $this->assertSame('string $myProperty Description', $fixture->render());
+        $this->assertSame('@property string $myProperty Description', $fixture->render());
 
         $fixture = new Property('myProperty', null, new Description('Description'));
-        $this->assertSame('$myProperty Description', $fixture->render());
+        $this->assertSame('@property $myProperty Description', $fixture->render());
 
         $fixture = new Property('myProperty');
-        $this->assertSame('$myProperty', $fixture->render());
+        $this->assertSame('@property $myProperty', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/PropertyWriteTest.php

@@ -43,17 +43,18 @@ class PropertyWriteTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new PropertyWrite('myProperty', new String_(), new Description('Description'));
-        $this->assertSame('string $myProperty Description', $fixture->render());
+        $this->assertSame('@property-write string $myProperty Description', $fixture->render());
 
         $fixture = new PropertyWrite('myProperty', null, new Description('Description'));
-        $this->assertSame('$myProperty Description', $fixture->render());
+        $this->assertSame('@property-write $myProperty Description', $fixture->render());
 
         $fixture = new PropertyWrite('myProperty');
-        $this->assertSame('$myProperty', $fixture->render());
+        $this->assertSame('@property-write $myProperty', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/ReturnTest.php

@@ -43,12 +43,13 @@ class ReturnTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new Return_(new String_(), new Description('Description'));
 
-        $this->assertSame('string Description', $fixture->render());
+        $this->assertSame('@return string Description', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/SeeTest.php

@@ -43,12 +43,13 @@ class SeeTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new See(new Fqsen('\DateTime'), new Description('Description'));
 
-        $this->assertSame('\DateTime Description', $fixture->render());
+        $this->assertSame('@see \DateTime Description', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/SinceTest.php

@@ -41,12 +41,13 @@ class SinceTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new Since('1.0', new Description('Description'));
 
-        $this->assertSame('1.0 Description', $fixture->render());
+        $this->assertSame('@since 1.0 Description', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/SourceTest.php

@@ -43,17 +43,18 @@ class SourceTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new Source(1, 10, new Description('Description'));
-        $this->assertSame('1 10 Description', $fixture->render());
+        $this->assertSame('@source 1 10 Description', $fixture->render());
 
         $fixture = new Source(1, null, new Description('Description'));
-        $this->assertSame('1 Description', $fixture->render());
+        $this->assertSame('@source 1 Description', $fixture->render());
 
         $fixture = new Source(1);
-        $this->assertSame('1', $fixture->render());
+        $this->assertSame('@source 1', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/ThrowsTest.php

@@ -43,12 +43,13 @@ class ThrowsTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new Throws(new String_(), new Description('Description'));
 
-        $this->assertSame('string Description', $fixture->render());
+        $this->assertSame('@throws string Description', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/UsesTest.php

@@ -43,12 +43,13 @@ class UsesTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new Uses(new Fqsen('\DateTime'), new Description('Description'));
 
-        $this->assertSame('\DateTime Description', $fixture->render());
+        $this->assertSame('@uses \DateTime Description', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/VarTest.php

@@ -43,17 +43,18 @@ class VarTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new Var_('myVariable', new String_(), new Description('Description'));
-        $this->assertSame('string $myVariable Description', $fixture->render());
+        $this->assertSame('@var string $myVariable Description', $fixture->render());
 
         $fixture = new Var_('myVariable', null, new Description('Description'));
-        $this->assertSame('$myVariable Description', $fixture->render());
+        $this->assertSame('@var $myVariable Description', $fixture->render());
 
         $fixture = new Var_('myVariable');
-        $this->assertSame('$myVariable', $fixture->render());
+        $this->assertSame('@var $myVariable', $fixture->render());
     }
 
     /**

tests/unit/DocBlock/Tags/VersionTest.php

@@ -41,12 +41,13 @@ class VersionTest extends \PHPUnit_Framework_TestCase
      * @uses   \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
      * @uses   \phpDocumentor\Reflection\DocBlock\Description
      * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::render
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\BaseTag::getName
      */
     public function testIfTagCanBeRenderedUsingDefaultFormatter()
     {
         $fixture = new Version('1.0', new Description('Description'));
 
-        $this->assertSame('1.0 Description', $fixture->render());
+        $this->assertSame('@version 1.0 Description', $fixture->render());
     }
 
     /**