Let tag handlers describe their expected format for InvalidTag reporting

Adds an `ExpectedFormat` interface a tag handler may opt into to advertise the syntax it expects together with a link to its canonical documentation. When `StandardTagFactory` falls back to `InvalidTag` because the handler rejected the body, it forwards those hints through the new `InvalidTag::withFormatHint()` method so downstream tooling (for example phpDocumentor's error reports) can surface a helpful explanation instead of only the raw exception. `Author` implements the interface as a first example since its lack of description support is a common source of confusion (see phpDocumentor/phpDocumentor#3378).

Fixes #346

Author: lacatoire

src/DocBlock/StandardTagFactory.php

@@ -32,6 +32,7 @@
 use phpDocumentor\Reflection\DocBlock\Tags\Factory\TemplateFactory;
 use phpDocumentor\Reflection\DocBlock\Tags\Factory\ThrowsFactory;
 use phpDocumentor\Reflection\DocBlock\Tags\Factory\VarFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\ExpectedFormat;
 use phpDocumentor\Reflection\DocBlock\Tags\Generic;
 use phpDocumentor\Reflection\DocBlock\Tags\InvalidTag;
 use phpDocumentor\Reflection\DocBlock\Tags\Link as LinkTag;
@@ -54,6 +55,8 @@
 use function call_user_func_array;
 use function get_class;
 use function is_object;
+use function is_string;
+use function is_subclass_of;
 use function preg_match;
 use function sprintf;
 use function strpos;
@@ -258,12 +261,29 @@ private function createTag(string $body, string $name, TypeContext $context): Ta
             /** @phpstan-var callable(string): ?Tag $callable */
             $tag = call_user_func_array($callable, $arguments);
 
-            return $tag ?? InvalidTag::create($body, $name);
+            return $tag ?? $this->createInvalidTag($handlerClassName, $body, $name);
         } catch (InvalidArgumentException $e) {
-            return InvalidTag::create($body, $name)->withError($e);
+            return $this->createInvalidTag($handlerClassName, $body, $name)->withError($e);
         }
     }
 
+    /**
+     * @param class-string<Tag>|Tag|Factory $handlerClassName
+     */
+    private function createInvalidTag($handlerClassName, string $body, string $name): InvalidTag
+    {
+        $invalidTag = InvalidTag::create($body, $name);
+
+        if (is_string($handlerClassName) && is_subclass_of($handlerClassName, ExpectedFormat::class)) {
+            $invalidTag = $invalidTag->withFormatHint(
+                $handlerClassName::getExpectedFormat(),
+                $handlerClassName::getDocumentationUrl()
+            );
+        }
+
+        return $invalidTag;
+    }
+
     /**
      * Determines the Fully Qualified Class Name of the Factory or Tag (containing a Factory Method `create`).
      *

src/DocBlock/Tags/Author.php

@@ -24,11 +24,21 @@
 /**
  * Reflection class for an {@}author tag in a Docblock.
  */
-final class Author extends BaseTag
+final class Author extends BaseTag implements ExpectedFormat
 {
     /** @var string register that this is the author tag. */
     protected string $name = 'author';
 
+    public static function getExpectedFormat(): string
+    {
+        return 'name [<email@example.com>]';
+    }
+
+    public static function getDocumentationUrl(): ?string
+    {
+        return 'https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/author.html';
+    }
+
     /** @var string The name of the author */
     private string $authorName;
 

src/DocBlock/Tags/ExpectedFormat.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ *  For the full copyright and license information, please view the LICENSE
+ *  file that was distributed with this source code.
+ *
+ * @link http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection\DocBlock\Tags;
+
+/**
+ * Tag handlers may implement this contract to describe what they expect as input. When the handler rejects a body
+ * and an {@see InvalidTag} is produced, the factory forwards these hints to the invalid tag so downstream tooling
+ * (for example phpDocumentor's error reporting) can explain the expected syntax instead of only showing the raw
+ * exception.
+ */
+interface ExpectedFormat
+{
+    /**
+     * Returns a short, human-readable description of the expected tag body, e.g. "name [<email>]".
+     */
+    public static function getExpectedFormat(): string;
+
+    /**
+     * Returns a URL pointing to the canonical documentation for the tag, or null when none is available.
+     */
+    public static function getDocumentationUrl(): ?string;
+}

src/DocBlock/Tags/InvalidTag.php

@@ -40,6 +40,10 @@ final class InvalidTag implements Tag
 
     private ?Throwable $throwable = null;
 
+    private ?string $expectedFormat = null;
+
+    private ?string $documentationUrl = null;
+
     private function __construct(string $name, string $body)
     {
         $this->name = $name;
@@ -51,6 +55,23 @@ public function getException(): ?Throwable
         return $this->throwable;
     }
 
+    /**
+     * Returns a short description of the format the corresponding tag handler expected, or null when the handler
+     * did not advertise one via {@see ExpectedFormat}.
+     */
+    public function getExpectedFormat(): ?string
+    {
+        return $this->expectedFormat;
+    }
+
+    /**
+     * Returns a URL pointing to the canonical documentation of the tag, or null when none is available.
+     */
+    public function getDocumentationUrl(): ?string
+    {
+        return $this->documentationUrl;
+    }
+
     public function getName(): string
     {
         return $this->name;
@@ -64,12 +85,35 @@ public static function create(string $body, string $name = ''): self
     public function withError(Throwable $exception): self
     {
         $this->flattenExceptionBacktrace($exception);
-        $tag            = new self($this->name, $this->body);
+        $tag            = $this->copy();
         $tag->throwable = $exception;
 
         return $tag;
     }
 
+    /**
+     * Returns a copy of this invalid tag that also carries hints about the syntax expected by the originating tag
+     * handler. Both arguments are optional so callers can advertise whichever information they have.
+     */
+    public function withFormatHint(?string $expectedFormat, ?string $documentationUrl = null): self
+    {
+        $tag                   = $this->copy();
+        $tag->expectedFormat   = $expectedFormat;
+        $tag->documentationUrl = $documentationUrl;
+
+        return $tag;
+    }
+
+    private function copy(): self
+    {
+        $tag                   = new self($this->name, $this->body);
+        $tag->throwable        = $this->throwable;
+        $tag->expectedFormat   = $this->expectedFormat;
+        $tag->documentationUrl = $this->documentationUrl;
+
+        return $tag;
+    }
+
     /**
      * Removes all complex types from backtrace
      *

tests/unit/DocBlock/StandardTagFactoryTest.php

@@ -21,6 +21,7 @@
 use phpDocumentor\Reflection\Assets\CustomServiceInterface;
 use phpDocumentor\Reflection\Assets\CustomTagFactory;
 use phpDocumentor\Reflection\DocBlock\Tags\Author;
+use phpDocumentor\Reflection\DocBlock\Tags\InvalidTag;
 use phpDocumentor\Reflection\DocBlock\Tags\Deprecated;
 use phpDocumentor\Reflection\DocBlock\Tags\Extends_;
 use phpDocumentor\Reflection\DocBlock\Tags\Formatter;
@@ -135,6 +136,28 @@ public function testCreatingASpecificTag(): void
         $this->assertSame('author', $tag->getName());
     }
 
+    /**
+     * @uses \phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService
+     * @uses \phpDocumentor\Reflection\DocBlock\Tags\Author
+     * @uses \phpDocumentor\Reflection\DocBlock\Tags\BaseTag
+     * @uses \phpDocumentor\Reflection\DocBlock\Tags\InvalidTag
+     *
+     * @covers ::__construct
+     * @covers ::create
+     */
+    public function testInvalidTagReceivesFormatHintFromHandler(): void
+    {
+        $context    = new Context('');
+        $tagFactory = StandardTagFactory::createInstance(m::mock(FqsenResolver::class));
+
+        $tag = $tagFactory->create('@author Mike <not-an-email>', $context);
+
+        $this->assertInstanceOf(InvalidTag::class, $tag);
+        $this->assertSame('author', $tag->getName());
+        $this->assertSame(Author::getExpectedFormat(), $tag->getExpectedFormat());
+        $this->assertSame(Author::getDocumentationUrl(), $tag->getDocumentationUrl());
+    }
+
     /**
      * @uses \phpDocumentor\Reflection\DocBlock\StandardTagFactory::addService
      * @uses \phpDocumentor\Reflection\DocBlock\Tags\See

tests/unit/DocBlock/Tags/InvalidTagTest.php

@@ -31,6 +31,37 @@ public function testCreationWithoutError(): void
         self::assertSame('name', $tag->getName());
         self::assertSame('@name Body', $tag->render());
         self::assertNull($tag->getException());
+        self::assertNull($tag->getExpectedFormat());
+        self::assertNull($tag->getDocumentationUrl());
+    }
+
+    /**
+     * @covers ::withFormatHint
+     * @covers ::getExpectedFormat
+     * @covers ::getDocumentationUrl
+     */
+    public function testCreationWithFormatHint(): void
+    {
+        $tag = InvalidTag::create('Body', 'name')
+            ->withFormatHint('expected format', 'https://example.com/doc');
+
+        self::assertSame('expected format', $tag->getExpectedFormat());
+        self::assertSame('https://example.com/doc', $tag->getDocumentationUrl());
+    }
+
+    /**
+     * @covers ::withFormatHint
+     * @covers ::withError
+     */
+    public function testFormatHintSurvivesWithError(): void
+    {
+        $tag = InvalidTag::create('Body', 'name')
+            ->withFormatHint('expected format', 'https://example.com/doc')
+            ->withError(new Exception('boom'));
+
+        self::assertSame('expected format', $tag->getExpectedFormat());
+        self::assertSame('https://example.com/doc', $tag->getDocumentationUrl());
+        self::assertNotNull($tag->getException());
     }
 
     /**