Improve and fix method tag

Author: Kirill Nesmeyanov

composer.json

@@ -10,7 +10,7 @@
     },
     "require": {
         "php": "^8.1",
-        "type-lang/parser": "^1.4"
+        "type-lang/parser": "^1.5"
     },
     "replace": {
         "type-lang/phpdoc-standard-tags": "*",

src/DocBlock/Tag/MethodTag/MethodTag.php

@@ -4,11 +4,11 @@
 
 namespace TypeLang\PHPDoc\DocBlock\Tag\MethodTag;
 
+use TypeLang\Parser\Node\Stmt\Callable\CallableParameterNode;
 use TypeLang\Parser\Node\Stmt\Callable\ParameterNode;
-use TypeLang\Parser\Node\Stmt\CallableTypeNode;
 use TypeLang\Parser\Node\Stmt\TypeStatement;
+use TypeLang\PHPDoc\DocBlock\Tag\OptionalTypeProviderInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\Tag;
-use TypeLang\PHPDoc\DocBlock\Tag\TypeProviderInterface;
 
 /**
  * The "`@method`" tag is used in situations where a class contains the
@@ -36,49 +36,40 @@
  * with a class or interface.
  *
  * ```
- *
  * * @method [static] <CallableType> [<description>]
  * * @method [static] <ReturnType> <CallableType> [<description>]
  * * @method [static] <CallableType>: <ReturnType> [<description>]
  * ```
  */
-class MethodTag extends Tag implements TypeProviderInterface
+class MethodTag extends Tag implements OptionalTypeProviderInterface
 {
+    /**
+     * @var list<ParameterNode|CallableParameterNode>
+     */
+    public readonly array $parameters;
+
     /**
      * @param non-empty-string $name
+     * @param non-empty-string $method
+     * @param iterable<mixed, ParameterNode|CallableParameterNode> $parameters
      */
     public function __construct(
         string $name,
-        public readonly CallableTypeNode $type,
-        protected readonly bool $static = false,
+        /**
+         * @var non-empty-string
+         */
+        public readonly string $method,
+        public readonly ?TypeStatement $type = null,
+        iterable $parameters = [],
+        public readonly bool $isStatic = false,
         \Stringable|string|null $description = null,
     ) {
-        parent::__construct($name, $description);
-    }
-
-    public function isStatic(): bool
-    {
-        return $this->static;
-    }
+        $this->parameters = match (true) {
+            $parameters instanceof \Traversable => \iterator_to_array($parameters, false),
+            \array_is_list($parameters) => $parameters,
+            default => \array_values($parameters),
+        };
 
-    public function getReturnType(): ?TypeStatement
-    {
-        return $this->type->type;
-    }
-
-    /**
-     * @return iterable<array-key, ParameterNode>
-     */
-    public function getParameters(): iterable
-    {
-        return $this->type->parameters;
-    }
-
-    /**
-     * @return non-empty-string
-     */
-    public function getMethodName(): string
-    {
-        return $this->type->name->toString();
+        parent::__construct($name, $description);
     }
 }

src/DocBlock/Tag/MethodTag/MethodTagFactory.php

@@ -5,9 +5,11 @@
 namespace TypeLang\PHPDoc\DocBlock\Tag\MethodTag;
 
 use TypeLang\Parser\Node\Stmt\CallableTypeNode;
+use TypeLang\Parser\Node\Stmt\NamedTypeNode;
 use TypeLang\Parser\Parser as TypesParser;
 use TypeLang\Parser\ParserInterface as TypesParserInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
+use TypeLang\PHPDoc\Exception\InvalidTagException;
 use TypeLang\PHPDoc\Parser\Content\OptionalTypeReader;
 use TypeLang\PHPDoc\Parser\Content\OptionalValueReader;
 use TypeLang\PHPDoc\Parser\Content\Stream;
@@ -30,39 +32,55 @@ public function create(string $tag, string $content, DescriptionParserInterface
         $stream = new Stream($tag, $content);
 
         $isStatic = $stream->apply(new OptionalValueReader('static')) !== null;
-        $returnType = $stream->apply(new TypeReader($this->parser));
-        $callableType = $stream->apply(new OptionalTypeReader($this->parser));
+
+        try {
+            $type = $stream->apply(new TypeReader($this->parser));
+        } catch (InvalidTagException $e) {
+            $type = $isStatic ? new NamedTypeNode('static') : throw $e;
+        }
+
+        $callable = null;
+
+        if (!$type instanceof CallableTypeNode) {
+            $callable = $stream->apply(new OptionalTypeReader($this->parser));
+        }
 
         // In case of return type has not been defined then we swap first
         // defined type as method signature definition.
-        if ($callableType === null) {
-            $callableType = $returnType;
-            $returnType = null;
+        if ($callable === null) {
+            $callable = $type;
+            $type = null;
         }
 
-        if (!$callableType instanceof CallableTypeNode) {
-            throw $stream->toException(
-                message: \sprintf(
-                    'The @%s annotation must contain the method signature',
-                    $tag,
-                ),
-            );
+        if (!$callable instanceof CallableTypeNode) {
+            throw $stream->toException(\sprintf(
+                'Tag @%s must contain the method signature',
+                $tag,
+            ));
         }
 
-        if ($callableType->type !== null && $returnType !== null) {
-            throw $stream->toException(
-                message: \sprintf('You can specify the return type of '
-                    . 'a method of the @%s annotation before or after the '
-                    . 'method`s signature, but not both', $tag),
-            );
+        if ($callable->type !== null && $type !== null) {
+            throw $stream->toException(\sprintf(
+                'You can specify the return type of the @%s tag before or '
+                    . 'after the method`s signature, but not both',
+                $tag,
+            ));
         }
 
-        $callableType->type ??= $returnType;
+        if (!$callable->name->isSimple()) {
+            throw $stream->toException(\sprintf(
+                'Tag @%s must contain the method name, but FQN "%s" given',
+                $tag,
+                $callable->name->toString(),
+            ));
+        }
 
         return new MethodTag(
             name: $tag,
-            type: $callableType,
-            static: $isStatic,
+            method: $callable->name->toString(),
+            type: $callable->type ?? $type,
+            parameters: $callable->parameters,
+            isStatic: $isStatic,
             description: $stream->toOptionalDescription($descriptions),
         );
     }