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

src/DocBlock/DescriptionFactory.php

@@ -14,6 +14,23 @@ namespace phpDocumentor\Reflection\DocBlock;
 
 use phpDocumentor\Reflection\Types\Context;
 
+/**
+ * Creates a new Description object given a body of text.
+ *
+ * Descriptions in phpDocumentor are somewhat complex entities as they can contain one or more tags inside their
+ * body that can be replaced with a readable output. The replacing is done by passing a Formatter object to the
+ * Description object's `render` method.
+ *
+ * In addition to the above does a Description support two types of escape sequences:
+ *
+ * 1. `{@}` to escape the `@` character to prevent it from being interpreted as part of a tag, i.e. `{{@}link}`
+ * 2. `{}` to escape the `}` character, this can be used if you want to use the `}` character in the description
+ *    of an inline tag.
+ *
+ * If a body consists of multiple lines then this factory will also remove any superfluous whitespace at the beginning
+ * of each line while maintaining any indentation that is used. This will prevent formatting parsers from tripping
+ * over unexpected spaces as can be observed with tag descriptions.
+ */
 class DescriptionFactory
 {
     /** @var TagFactory */
@@ -45,11 +62,16 @@ class DescriptionFactory
     }
 
     /**
-     * @param $contents
+     * Strips the contents from superfluous whitespace and splits the description into a series of tokens.
-     * @return array
+     *
+     * @param string $contents
+     *
+     * @return string[] A series of tokens of which the description text is composed.
      */
     private function lex($contents)
     {
+        $contents = $this->removeSuperfluousStartingWhitespace($contents);
+
         // performance optimalization; if there is no inline tag, don't bother splitting it up.
         if (strpos($contents, '{@') === false) {
             return [$contents];
@@ -99,6 +121,7 @@ class DescriptionFactory
         $count = count($tokens);
         $tagCount = 0;
         $tags  = [];
+
         for ($i = 1; $i < $count; $i += 2) {
             $tags[] = $this->tagFactory->create($tokens[$i], $context);
             $tokens[$i] = '%' . ++$tagCount . '$s';
@@ -114,4 +137,55 @@ class DescriptionFactory
         return [implode('', $tokens), $tags];
     }
 
+    /**
+     * Removes the superfluous from a multi-line description.
+     *
+     * When a description has more than one line then it can happen that the second and subsequent lines have an
+     * additional indentation. This is commonly in use with tags like this:
+     *
+     *     {@}since 1.1.0 This is an example
+     *         description where we have an
+     *         indentation in the second and
+     *         subsequent lines.
+     *
+     * If we do not normalize the indentation then we have superfluous whitespace on the second and subsequent
+     * lines and this may cause rendering issues when, for example, using a Markdown converter.
+     *
+     * @param string $contents
+     *
+     * @return string
+     */
+    private function removeSuperfluousStartingWhitespace($contents)
+    {
+        $lines = explode("\n", $contents);
+
+        // if there is only one line then we don't have lines with superfluous whitespace and
+        // can use the contents as-is
+        if (count($lines) <= 1) {
+            return $contents;
+        }
+
+        // determine how many whitespace characters need to be stripped
+        $startingSpaceCount = 9999999;
+        for ($i = 1; $i < count($lines); $i++) {
+            // lines with a no length do not count as they are not indented at all
+            if (strlen(trim($lines[$i])) === 0) {
+                continue;
+            }
+
+            // determine the number of prefixing spaces by checking the difference in line length before and after
+            // an ltrim
+            $startingSpaceCount = min($startingSpaceCount, strlen($lines[$i]) - strlen(ltrim($lines[$i])));
+        }
+
+        // strip the number of spaces from each line
+        if ($startingSpaceCount > 0) {
+            for ($i = 1; $i < count($lines); $i++) {
+                $lines[$i] = substr($lines[$i], $startingSpaceCount);
+            }
+        }
+
+        return implode("\n", $lines);
+    }
+
 }

src/DocBlock/Serializer.php

@@ -127,7 +127,8 @@ class Serializer
     private function addTagBlock(DocBlock $docblock, $wrapLength, $indent, $comment)
     {
         foreach ($docblock->getTags() as $tag) {
-            $tagText = (string)$tag;
+            $formatter = new DocBlock\Tags\Formatter\PassthroughFormatter();
+            $tagText   = $formatter->format($tag);
             if ($wrapLength !== null) {
                 $tagText = wordwrap($tagText, $wrapLength);
             }

src/DocBlock/Tags/Example.php

@@ -1,11 +1,11 @@
 <?php
 /**
- * phpDocumentor
+ * This file is part of phpDocumentor.
  *
- * PHP Version 5.3
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
  *
- * @author    Vasil Rangelov <[email protected]>
+ * @copyright 2010-2015 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
  */
@@ -15,25 +15,20 @@ namespace phpDocumentor\Reflection\DocBlock\Tags;
 use phpDocumentor\Reflection\DocBlock\Tag;
 
 /**
- * Reflection class for a @example tag in a Docblock.
+ * Reflection class for a {@}example tag in a Docblock.
- *
- * @author  Vasil Rangelov <[email protected]>
- * @license http://www.opensource.org/licenses/mit-license.php MIT
- * @link    http://phpdoc.org
  */
-class Example extends Source
+final class Example extends BaseTag
 {
     /**
-     * @var string Path to a file to use as an example.
+     * @var string Path to a file to use as an example. May also be an absolute URI.
-     *     May also be an absolute URI.
      */
-    protected $filePath = '';
+    private $filePath = '';
 
     /**
-     * @var bool Whether the file path component represents an URI.
+     * @var bool Whether the file path component represents an URI. This determines how the file portion
-     *     This determines how the file portion appears at {@link getContent()}.
+     *     appears at {@link getContent()}.
      */
-    protected $isURI = false;
+    private $isURI = false;
 
     /**
      * {@inheritdoc}
@@ -57,40 +52,35 @@ class Example extends Source
     /**
      * {@inheritdoc}
      */
-    public function setContent($content)
+    public static function create($body)
     {
-        Tag::setContent($content);
+        // File component: File path in quotes or File URI / Source information
-        if (preg_match(
+        if (! preg_match('/^(?:\"([^\"]+)\"|(\S+))(?:\s+(.*))?$/sux', $body, $matches)) {
-            '/^
+            return null;
-                # File component
+        }
-                (?:
+
-                    # File path in quotes
+        $filePath = null;
-                    \"([^\"]+)\"
+        $fileUri  = null;
-                    |
-                    # File URI
-                    (\S+)
-                )
-                # Remaining content (parsed by SourceTag)
-                (?:\s+(.*))?
-            $/sux',
-            $this->description,
-            $matches
-        )) {
         if ('' !== $matches[1]) {
-                $this->setFilePath($matches[1]);
+            $filePath = $matches[1];
         } else {
-                $this->setFileURI($matches[2]);
+            $fileUri = $matches[2];
         }
 
-            if (isset($matches[3])) {
+        $startingLine = 1;
-                parent::setContent($matches[3]);
+        $lineCount    = null;
-            } else {
+        $description  = null;
-                $this->setDescription('');
+
+        // Starting line / Number of lines / Description
+        if (preg_match('/^([1-9]\d*)\s*(?:((?1))\s+)?(.*)$/sux', $matches[3], $matches)) {
+            $startingLine = (int)$matches[1];
+            if (isset($matches[2]) && $matches[2] !== '') {
+                $lineCount = (int)$matches[2];
             }
-            $this->description = $content;
+            $description = $matches[3];
         }
 
-        return $this;
+        return new static($filePath, $fileUri, $startingLine, $lineCount, $description);
     }
 
     /**

src/DocBlock/Tags/Formatter/PassthroughFormatter.php

@@ -26,6 +26,6 @@ class PassthroughFormatter implements Formatter
      */
     public function format(Tag $tag)
     {
-        return (string)$tag;
+        return '@' . $tag->getName() . ' ' . (string)$tag;
     }
 }

src/DocBlock/Tags/Generic.php

@@ -68,7 +68,7 @@ class Generic extends BaseTag
      */
     public function __toString()
     {
-        return '@' . $this->getName() . ($this->description ? ' ' . $this->description->render() : '');
+        return ($this->description ? $this->description->render() : '');
     }
 
     /**

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 containing } that is literal.'],
-            ['This is text for a description with {} that is not a tag.'],
+            ['This is text for a description with {just a text} 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}.']
+    }
+
+    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());
     }
 
     /**