Add more common tag interfaces

Author: SerafimArts

src/DocBlock.php

@@ -7,9 +7,10 @@
 use TypeLang\PHPDoc\Tag\Description;
 use TypeLang\PHPDoc\Tag\DescriptionInterface;
 use TypeLang\PHPDoc\Tag\DescriptionProviderInterface;
+use TypeLang\PHPDoc\Tag\OptionalDescriptionProviderInterface;
 use TypeLang\PHPDoc\Tag\TagInterface;
-use TypeLang\PHPDoc\Tag\TagProvider;
-use TypeLang\PHPDoc\Tag\TagProviderInterface;
+use TypeLang\PHPDoc\Tag\TagsProvider;
+use TypeLang\PHPDoc\Tag\TagsProviderInterface;
 
 /**
  * This class represents structure containing a description and a set of tags
@@ -19,12 +20,12 @@
  * @template-implements \ArrayAccess<int<0, max>, TagInterface|null>
  */
 final class DocBlock implements
-    DescriptionProviderInterface,
-    TagProviderInterface,
+    OptionalDescriptionProviderInterface,
+    TagsProviderInterface,
     \IteratorAggregate,
     \ArrayAccess
 {
-    use TagProvider;
+    use TagsProvider;
 
     private readonly DescriptionInterface $description;
 

src/Tag/Description.php

@@ -9,7 +9,7 @@
  */
 class Description implements DescriptionInterface, \IteratorAggregate
 {
-    use TagProvider;
+    use TagsProvider;
 
     protected readonly string $template;
 

src/Tag/DescriptionInterface.php

@@ -4,7 +4,7 @@
 
 namespace TypeLang\PHPDoc\Tag;
 
-interface DescriptionInterface extends TagProviderInterface, \Stringable
+interface DescriptionInterface extends TagsProviderInterface, \Stringable
 {
     /**
      * Returns the body template.

src/Tag/DescriptionProviderInterface.php

@@ -4,13 +4,13 @@
 
 namespace TypeLang\PHPDoc\Tag;
 
-interface DescriptionProviderInterface
+interface DescriptionProviderInterface extends OptionalDescriptionProviderInterface
 {
     /**
      * Returns description object which can be represented as a string and
      * contains additional information.
      *
      * @psalm-immutable Each call to the method must return the same value.
      */
-    public function getDescription(): ?DescriptionInterface;
+    public function getDescription(): DescriptionInterface;
 }

src/Tag/OptionalDescriptionProviderInterface.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Tag;
+
+interface OptionalDescriptionProviderInterface
+{
+    /**
+     * Returns description object which can be represented as a string and
+     * contains additional information.
+     *
+     * @psalm-immutable Each call to the method must return the same value.
+     */
+    public function getDescription(): ?DescriptionInterface;
+}

src/Tag/OptionalTypeProviderInterface.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Tag;
+
+use TypeLang\Parser\Node\Stmt\TypeStatement;
+
+/**
+ * Every class that implements a given interface is an implementation of a
+ * tag that contains type information (that is, an AST object).
+ *
+ * Requires a `type-lang/parser` dependency for {@see TypeStatement} support.
+ *
+ * @psalm-suppress UndefinedClass : Expects optional `type-lang/parser` dependency.
+ */
+interface OptionalTypeProviderInterface
+{
+    /**
+     * Returns an AST object of the type or {@see null} in case the
+     * type is not specified.
+     *
+     * @psalm-immutable Each call to the method must return the same value.
+     */
+    public function getType(): ?TypeStatement;
+}

src/Tag/OptionalVariableNameProviderInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Tag;
+
+interface OptionalVariableNameProviderInterface
+{
+    /**
+     * Returns the name of the variable (parameter, field, etc.) to
+     * which this tag is attached or {@see null} in case of the tag does
+     * not contain a name.
+     *
+     * @psalm-immutable Each call to the method must return the same value.
+     *
+     * @return non-empty-string|null
+     */
+    public function getVariable(): ?string;
+}

src/Tag/TagInterface.php

@@ -4,7 +4,7 @@
 
 namespace TypeLang\PHPDoc\Tag;
 
-interface TagInterface extends DescriptionProviderInterface, \Stringable
+interface TagInterface extends OptionalDescriptionProviderInterface, \Stringable
 {
     /**
      * Returns the non-empty tag name string without the '@' prefix.

src/Tag/TagProvider.php renamed to src/Tag/TagsProvider.php

@@ -5,16 +5,16 @@
 namespace TypeLang\PHPDoc\Tag;
 
 /**
- * @mixin TagProviderInterface
+ * @mixin TagsProviderInterface
  * @mixin \IteratorAggregate
  *
- * @psalm-require-implements TagProviderInterface
+ * @psalm-require-implements TagsProviderInterface
  * @psalm-require-implements \IteratorAggregate
  *
  * @internal This is an internal library trait, please do not use it in your code.
  * @psalm-internal TypeLang\PHPDoc\Tag
  */
-trait TagProvider
+trait TagsProvider
 {
     /**
      * @var list<TagInterface>
@@ -32,9 +32,9 @@ protected function bootTagProvider(iterable $tags): void
     }
 
     /**
-     * @see TagProviderInterface::getTags()
-     *
      * @return list<TagInterface>
+     *@see TagsProviderInterface::getTags()
+     *
      */
     public function getTags(): array
     {
@@ -51,7 +51,7 @@ public function getIterator(): \Traversable
 
             $description = $tag->getDescription();
 
-            if ($description instanceof TagProviderInterface) {
+            if ($description instanceof TagsProviderInterface) {
                 yield from $description;
             }
         }

src/Tag/TagProviderInterface.php renamed to src/Tag/TagsProviderInterface.php

@@ -10,7 +10,7 @@
  * @internal This is an internal library interface, please do not use it in your code.
  * @psalm-internal TypeLang\PHPDoc\Tag
  */
-interface TagProviderInterface extends \Traversable, \Countable
+interface TagsProviderInterface extends \Traversable, \Countable
 {
     /**
      * Returns the tags for this object.

src/Tag/TypeProviderInterface.php

@@ -7,17 +7,14 @@
 use TypeLang\Parser\Node\Stmt\TypeStatement;
 
 /**
- * Every class that implements a given interface is an implementation of a
- * tag that contains type information (that is, an AST object).
- *
- * Requires a `type-lang/parser` dependency for {@see TypeStatement} support.
- *
  * @psalm-suppress UndefinedClass : Expects optional `type-lang/parser` dependency.
  */
-interface TypeProviderInterface
+interface TypeProviderInterface extends OptionalTypeProviderInterface
 {
     /**
      * Returns an AST object of the type.
+     *
+     * @psalm-immutable Each call to the method must return the same value.
      */
     public function getType(): TypeStatement;
 }

src/Tag/VariableNameProviderInterface.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Tag;
+
+interface VariableNameProviderInterface extends OptionalVariableNameProviderInterface
+{
+    /**
+     * Returns the name of the variable (parameter, field, etc.) to
+     * which this tag is attached.
+     *
+     * @psalm-immutable Each call to the method must return the same value.
+     *
+     * @return non-empty-string
+     */
+    public function getVariable(): string;
+}