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.

src/DocBlock/DescriptionFactory.php

@@ -69,10 +69,7 @@ class DescriptionFactory
         $tags     = [];
 
         for ($i = 1; $i < $count; $i += 2) {
-            $tag = $this->tagFactory->create($tokens[$i], $context);
-            if ($tag !== null) {
-                $tags[] = $tag;
-            }
+            $tags[]     = $this->tagFactory->create($tokens[$i], $context);
             $tokens[$i] = '%' . ++$tagCount . '$s';
         }
 

src/DocBlock/StandardTagFactory.php

@@ -19,6 +19,7 @@ use phpDocumentor\Reflection\DocBlock\Tags\Covers;
 use phpDocumentor\Reflection\DocBlock\Tags\Deprecated;
 use phpDocumentor\Reflection\DocBlock\Tags\Factory\StaticMethod;
 use phpDocumentor\Reflection\DocBlock\Tags\Generic;
+use phpDocumentor\Reflection\DocBlock\Tags\InvalidTag;
 use phpDocumentor\Reflection\DocBlock\Tags\Link as LinkTag;
 use phpDocumentor\Reflection\DocBlock\Tags\Method;
 use phpDocumentor\Reflection\DocBlock\Tags\Param;
@@ -138,7 +139,7 @@ final class StandardTagFactory implements TagFactory
     /**
      * {@inheritDoc}
      */
-    public function create(string $tagLine, ?TypeContext $context = null) : ?Tag
+    public function create(string $tagLine, ?TypeContext $context = null) : Tag
     {
         if (!$context) {
             $context = new TypeContext('');
@@ -215,7 +216,7 @@ final class StandardTagFactory implements TagFactory
      * Creates a new tag object with the given name and body or returns null if the tag name was recognized but the
      * body was invalid.
      */
-    private function createTag(string $body, string $name, TypeContext $context) : ?Tag
+    private function createTag(string $body, string $name, TypeContext $context) : Tag
     {
         $handlerClassName = $this->findHandlerClassName($name, $context);
         $arguments        = $this->getArgumentsForParametersFromWiring(
@@ -228,7 +229,7 @@ final class StandardTagFactory implements TagFactory
             $callable = [$handlerClassName, 'create'];
             return call_user_func_array($callable, $arguments);
         } catch (InvalidArgumentException $e) {
-            return null;
+            return InvalidTag::create($body, $name, $e);
         }
     }
 

src/DocBlock/TagFactory.php

@@ -49,7 +49,7 @@ interface TagFactory
      *
      * @throws InvalidArgumentException If an invalid tag line was presented.
      */
-    public function create(string $tagLine, ?TypeContext $context = null) : ?Tag;
+    public function create(string $tagLine, ?TypeContext $context = null) : Tag;
 
     /**
      * Registers a service with the Service Locator using the FQCN of the class or the alias, if provided.

src/DocBlock/Tags/InvalidTag.php

@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\DocBlock\Tags;
+
+use phpDocumentor\Reflection\DocBlock\Tag;
+use Throwable;
+use Webmozart\Assert\Assert;
+
+/**
+ * This class represents an exception during the tag creation
+ *
+ * Since the internals of the library are relaying on the correct syntax of a docblock
+ * we cannot simply throw exceptions at all time because the exceptions will break the creation of a
+ * docklock. Just silently ignore the exceptions is not an option because the user as an issue to fix.
+ *
+ * This tag holds that error information until a using application is able to display it. The object wil just behave
+ * like any normal tag. So the normal application flow will not break.
+ */
+final class InvalidTag implements Tag
+{
+    /** @var string */
+    private $name;
+
+    /** @var string */
+    private $body;
+
+    /** @var Throwable */
+    private $throwable;
+
+    private function __construct(string $name, string $body, Throwable $throwable)
+    {
+        $this->name      = $name;
+        $this->body      = $body;
+        $this->throwable = $throwable;
+    }
+
+    public function getException() : Throwable
+    {
+        return $this->throwable;
+    }
+
+    public function getName() : string
+    {
+        return $this->name;
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public static function create(string $body, string $name = '', ?Throwable $exception = null)
+    {
+        Assert::notNull($exception);
+
+        return new self($name, $body, $exception);
+    }
+
+    public function render(?Formatter $formatter = null) : string
+    {
+        if ($formatter === null) {
+            $formatter = new Formatter\PassthroughFormatter();
+        }
+
+        return $formatter->format($this);
+    }
+
+    public function __toString() : string
+    {
+        return $this->body;
+    }
+}