Fix issue when processing invalid tags

When invalid tags are processed a null was returned causing all kind
of issues in the normal behavior of this libary. As a solution a generic tag
could be created. But that would just drop the error information in.
Therefore a new tag was introduced, `invalidTag` the tag is just like the
generic tag but does contain the error triggered during the creation of the
tag. Which might help applications like phpdocumentor to display validation issues.

tests/unit/DocBlock/DescriptionFactoryTest.php

@@ -13,7 +13,9 @@ declare(strict_types=1);
 
 namespace phpDocumentor\Reflection\DocBlock;
 
+use Exception;
 use Mockery as m;
+use phpDocumentor\Reflection\DocBlock\Tags\InvalidTag;
 use phpDocumentor\Reflection\DocBlock\Tags\Link as LinkTag;
 use phpDocumentor\Reflection\Types\Context;
 use PHPUnit\Framework\TestCase;
@@ -162,6 +164,31 @@ DESCRIPTION;
         $this->assertSame($expectedDescription, $description->render());
     }
 
+    /**
+     * @uses \phpDocumentor\Reflection\DocBlock\Description
+     * @uses \phpDocumentor\Reflection\DocBlock\Tags\InvalidTag
+     * @uses \phpDocumentor\Reflection\DocBlock\Tags\Formatter\PassthroughFormatter
+     * @uses \phpDocumentor\Reflection\Types\Context
+     *
+     * @covers ::__construct
+     * @covers ::create
+     */
+    public function testDescriptionWithBrokenInlineTags() : void
+    {
+        $contents   = 'This {@see $name} is a broken use case, but used in real life.';
+        $context    = new Context('');
+        $tagFactory = m::mock(TagFactory::class);
+        $tagFactory->shouldReceive('create')
+            ->once()
+            ->with('@see $name', $context)
+            ->andReturn(InvalidTag::create('$name', 'see', new Exception()));
+
+        $factory     = new DescriptionFactory($tagFactory);
+        $description = $factory->create($contents, $context);
+
+        $this->assertSame($contents, $description->render());
+    }
+
     /**
      * Provides a series of example strings that the parser should correctly interpret and return.
      *

tests/unit/DocBlockFactoryTest.php

@@ -279,37 +279,4 @@ DOCBLOCK
 
         $this->assertInstanceOf(DocBlock::class, $docblock);
     }
-
-    /**
-     * @uses \phpDocumentor\Reflection\DocBlock\DescriptionFactory
-     * @uses \phpDocumentor\Reflection\DocBlock\Description
-     *
-     * @covers ::__construct
-     * @covers ::create
-     */
-    public function testTagsAreFilteredForNullValues() : void
-    {
-        $tagString = <<<TAG
-@author Mike van Riel <[email protected]> This is with
-  multiline description.
-TAG;
-
-        $tagFactory = m::mock(TagFactory::class);
-        $tagFactory->shouldReceive('create')->with($tagString, m::any())->andReturn(null);
-
-        $fixture = new DocBlockFactory(new DescriptionFactory($tagFactory), $tagFactory);
-
-        $given = <<<DOCBLOCK
-/**
- * This is a summary.
- *
- * @author Mike van Riel <[email protected]> This is with
- *   multiline description.
- */
-DOCBLOCK;
-
-        $docblock = $fixture->create($given, new Context(''));
-
-        $this->assertEquals([], $docblock->getTags());
-    }
 }