Split "no type" and "invalid type" to 2 separate exceptions

Kirill Nesmeyanov · Kirill Nesmeyanov · commit 0c6376a1fe9a · 2025-03-10T12:30:46.000+03:00
diff --git a/composer.json b/composer.json
@@ -26,6 +26,7 @@
     },
     "require-dev": {
         "friendsofphp/php-cs-fixer": "^3.70",
+        "jetbrains/phpstorm-attributes": "^1.0",
         "phpstan/phpstan": "^2.1",
         "phpstan/phpstan-strict-rules": "^2.0",
         "phpunit/phpunit": "^10.5|^11.0|^12.0",
diff --git a/resources/.meta-storm.xml b/resources/.meta-storm.xml
@@ -2,15 +2,17 @@
 <meta-storm xmlns="meta-storm">
     <definitions>
 
-        <classConstructor class="\TypeLang\PHPDoc\ParserInterface"
-                          argument="1">
+        <classMethod class="\TypeLang\PHPDoc\ParserInterface"
+                          method="parse"
+                          argument="0">
             <languageInjection language="InjectablePHP" />
-        </classConstructor>
+        </classMethod>
 
-        <classConstructor class="\TypeLang\PHPDoc\Parser"
-                          argument="1">
+        <classMethod class="\TypeLang\PHPDoc\Parser"
+                     method="parse"
+                     argument="0">
             <languageInjection language="InjectablePHP" />
-        </classConstructor>
+        </classMethod>
 
     </definitions>
 </meta-storm>
diff --git a/src/DocBlock/Tag/MethodTag/MethodTagFactory.php b/src/DocBlock/Tag/MethodTag/MethodTagFactory.php
@@ -11,7 +11,7 @@
 use TypeLang\PHPDoc\Parser\Content\OptionalTypeReader;
 use TypeLang\PHPDoc\Parser\Content\OptionalValueReader;
 use TypeLang\PHPDoc\Parser\Content\Stream;
-use TypeLang\PHPDoc\Parser\Content\TypeParserReader;
+use TypeLang\PHPDoc\Parser\Content\TypeReader;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 
 /**
@@ -30,7 +30,7 @@ public function create(string $tag, string $content, DescriptionParserInterface
         $stream = new Stream($tag, $content);
 
         $isStatic = $stream->apply(new OptionalValueReader('static')) !== null;
-        $returnType = $stream->apply(new TypeParserReader($this->parser));
+        $returnType = $stream->apply(new TypeReader($this->parser));
         $callableType = $stream->apply(new OptionalTypeReader($this->parser));
 
         // In case of return type has not been defined then we swap first
diff --git a/src/DocBlock/Tag/ParamTag/ParamTagFactory.php b/src/DocBlock/Tag/ParamTag/ParamTagFactory.php
@@ -8,7 +8,7 @@
 use TypeLang\Parser\ParserInterface as TypesParserInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
 use TypeLang\PHPDoc\Parser\Content\Stream;
-use TypeLang\PHPDoc\Parser\Content\TypeParserReader;
+use TypeLang\PHPDoc\Parser\Content\TypeReader;
 use TypeLang\PHPDoc\Parser\Content\VariableNameReader;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 
@@ -39,7 +39,7 @@ public function create(string $tag, string $content, DescriptionParserInterface
         $output = $variadic = false;
 
         if (!$this->isVariable($stream->value)) {
-            $type = $stream->apply(new TypeParserReader($this->parser));
+            $type = $stream->apply(new TypeReader($this->parser));
         }
 
         if (\str_starts_with($stream->value, '&')) {
diff --git a/src/DocBlock/Tag/PropertyTag/PropertyTagFactory.php b/src/DocBlock/Tag/PropertyTag/PropertyTagFactory.php
@@ -8,7 +8,7 @@
 use TypeLang\Parser\ParserInterface as TypesParserInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
 use TypeLang\PHPDoc\Parser\Content\Stream;
-use TypeLang\PHPDoc\Parser\Content\TypeParserReader;
+use TypeLang\PHPDoc\Parser\Content\TypeReader;
 use TypeLang\PHPDoc\Parser\Content\VariableNameReader;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 
@@ -29,7 +29,7 @@ public function create(string $tag, string $content, DescriptionParserInterface
         $type = null;
 
         if (!\str_starts_with($stream->value, '$')) {
-            $type = $stream->apply(new TypeParserReader($this->parser));
+            $type = $stream->apply(new TypeReader($this->parser));
         }
 
         $variable = $stream->apply(new VariableNameReader());
diff --git a/src/DocBlock/Tag/ReturnTag/ReturnTagFactory.php b/src/DocBlock/Tag/ReturnTag/ReturnTagFactory.php
@@ -8,7 +8,7 @@
 use TypeLang\Parser\ParserInterface as TypesParserInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
 use TypeLang\PHPDoc\Parser\Content\Stream;
-use TypeLang\PHPDoc\Parser\Content\TypeParserReader;
+use TypeLang\PHPDoc\Parser\Content\TypeReader;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 
 /**
@@ -28,7 +28,7 @@ public function create(string $tag, string $content, DescriptionParserInterface
 
         return new ReturnTag(
             name: $tag,
-            type: $stream->apply(new TypeParserReader($this->parser)),
+            type: $stream->apply(new TypeReader($this->parser)),
             description: $stream->toOptionalDescription($descriptions),
         );
     }
diff --git a/src/DocBlock/Tag/TemplateExtendsTag/TemplateExtendsTagFactory.php b/src/DocBlock/Tag/TemplateExtendsTag/TemplateExtendsTagFactory.php
@@ -8,7 +8,7 @@
 use TypeLang\Parser\ParserInterface as TypesParserInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
 use TypeLang\PHPDoc\Parser\Content\Stream;
-use TypeLang\PHPDoc\Parser\Content\TypeParserReader;
+use TypeLang\PHPDoc\Parser\Content\TypeReader;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 
 /**
@@ -27,7 +27,7 @@ public function create(string $tag, string $content, DescriptionParserInterface
     {
         $stream = new Stream($tag, $content);
 
-        $type = $stream->apply(new TypeParserReader($this->parser));
+        $type = $stream->apply(new TypeReader($this->parser));
 
         return new TemplateExtendsTag(
             name: $tag,
diff --git a/src/DocBlock/Tag/ThrowsTag/ThrowsTagFactory.php b/src/DocBlock/Tag/ThrowsTag/ThrowsTagFactory.php
@@ -8,7 +8,7 @@
 use TypeLang\Parser\ParserInterface as TypesParserInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
 use TypeLang\PHPDoc\Parser\Content\Stream;
-use TypeLang\PHPDoc\Parser\Content\TypeParserReader;
+use TypeLang\PHPDoc\Parser\Content\TypeReader;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 
 /**
@@ -28,7 +28,7 @@ public function create(string $tag, string $content, DescriptionParserInterface
 
         return new ThrowsTag(
             name: $tag,
-            type: $stream->apply(new TypeParserReader($this->parser)),
+            type: $stream->apply(new TypeReader($this->parser)),
             description: $stream->toOptionalDescription($descriptions),
         );
     }
diff --git a/src/DocBlock/Tag/VarTag/VarTagFactory.php b/src/DocBlock/Tag/VarTag/VarTagFactory.php
@@ -9,7 +9,7 @@
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
 use TypeLang\PHPDoc\Parser\Content\OptionalVariableNameReader;
 use TypeLang\PHPDoc\Parser\Content\Stream;
-use TypeLang\PHPDoc\Parser\Content\TypeParserReader;
+use TypeLang\PHPDoc\Parser\Content\TypeReader;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 
 /**
@@ -27,7 +27,7 @@ public function create(string $tag, string $content, DescriptionParserInterface
     {
         $stream = new Stream($tag, $content);
 
-        $type = $stream->apply(new TypeParserReader($this->parser));
+        $type = $stream->apply(new TypeReader($this->parser));
         $variable = $stream->apply(new OptionalVariableNameReader());
 
         return new VarTag(
diff --git a/src/Parser.php b/src/Parser.php
@@ -4,6 +4,7 @@
 
 namespace TypeLang\PHPDoc;
 
+use JetBrains\PhpStorm\Language;
 use TypeLang\PHPDoc\DocBlock\DocBlock;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\MutableTagFactoryInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactory;
@@ -68,7 +69,7 @@ public function register(string|array $tags, TagFactoryInterface $delegate): voi
     /**
      * @throws RuntimeExceptionInterface
      */
-    public function parse(string $docblock): DocBlock
+    public function parse(#[Language('InjectablePHP')] string $docblock): DocBlock
     {
         $mapper = new SourceMap();
 
diff --git a/src/Parser/Content/TypeReader.php b/src/Parser/Content/TypeReader.php
@@ -12,7 +12,7 @@
 /**
  * @template-extends Reader<TypeStatement>
  */
-final class TypeParserReader extends Reader
+final class TypeReader extends Reader
 {
     public function __construct(
         private readonly TypesParserInterface $parser,
@@ -27,10 +27,19 @@ public function __invoke(Stream $stream): TypeStatement
         try {
             $type = $this->parser->parse($stream->value);
         } catch (ParserExceptionInterface $e) {
-            throw $stream->toException(
-                message: \sprintf('Tag @%s contains an incorrect type', $stream->tag),
-                previous: $e,
-            );
+            // @phpstan-ignore-next-line : Property is defined
+            if (\trim($stream->value) === '') {
+                throw $stream->toException(\sprintf(
+                    'Tag @%s expects the type to be defined',
+                    $stream->tag,
+                ), $e);
+            }
+
+            throw $stream->toException(\sprintf(
+                'Tag @%s contains an incorrect type "%s"',
+                $stream->tag,
+                \trim($stream->value),
+            ), $e);
         }
 
         // @phpstan-ignore-next-line : Property is defined
diff --git a/src/ParserInterface.php b/src/ParserInterface.php
@@ -4,12 +4,13 @@
 
 namespace TypeLang\PHPDoc;
 
+use JetBrains\PhpStorm\Language;
 use TypeLang\PHPDoc\DocBlock\DocBlock;
 
 interface ParserInterface
 {
     /**
      * @param string $docblock a string containing the DocBlock to parse
      */
-    public function parse(string $docblock): DocBlock;
+    public function parse(#[Language('InjectablePHP')] string $docblock): DocBlock;
 }
diff --git a/tests/Functional/Tag/ParamTagTest.php b/tests/Functional/Tag/ParamTagTest.php
@@ -15,7 +15,7 @@ public function testEmptyTag(): void
         $tag = $this->parseTag('@param');
 
         self::assertInstanceOf(InvalidTag::class, $tag);
-        self::assertSame('Tag @param contains an incorrect type', $tag->reason->getMessage());
+        self::assertSame('Tag @param expects the type to be defined', $tag->reason->getMessage());
         self::assertNull($tag->description);
     }
 
@@ -24,7 +24,7 @@ public function testTagWithInvalidType(): void
         $tag = $this->parseTag('@param <example>');
 
         self::assertInstanceOf(InvalidTag::class, $tag);
-        self::assertSame('Tag @param contains an incorrect type', $tag->reason->getMessage());
+        self::assertSame('Tag @param contains an incorrect type "<example>"', $tag->reason->getMessage());
         self::assertEquals(new Description('<example>'), $tag->description);
     }
 
diff --git a/tests/Functional/Tag/VarTagTest.php b/tests/Functional/Tag/VarTagTest.php
@@ -15,7 +15,7 @@ public function testEmptyTag(): void
         $tag = $this->parseTag('@var');
 
         self::assertInstanceOf(InvalidTag::class, $tag);
-        self::assertSame('Tag @var contains an incorrect type', $tag->reason->getMessage());
+        self::assertSame('Tag @var expects the type to be defined', $tag->reason->getMessage());
         self::assertNull($tag->description);
     }
 
@@ -24,7 +24,7 @@ public function testTagWithInvalidType(): void
         $tag = $this->parseTag('@var <example>');
 
         self::assertInstanceOf(InvalidTag::class, $tag);
-        self::assertSame('Tag @var contains an incorrect type', $tag->reason->getMessage());
+        self::assertSame('Tag @var contains an incorrect type "<example>"', $tag->reason->getMessage());
         self::assertEquals(new Description('<example>'), $tag->description);
     }
 
