Add tags and description interfaces

SerafimArts · SerafimArts · commit 9e847aeca877 · 2024-04-03T01:36:10.000+03:00
diff --git a/src/DocBlock.php b/src/DocBlock.php
@@ -5,28 +5,44 @@
 namespace TypeLang\PHPDoc;
 
 use TypeLang\PHPDoc\Tag\Description;
-use TypeLang\PHPDoc\Tag\Tag;
+use TypeLang\PHPDoc\Tag\DescriptionInterface;
+use TypeLang\PHPDoc\Tag\DescriptionProviderInterface;
+use TypeLang\PHPDoc\Tag\TagInterface;
 use TypeLang\PHPDoc\Tag\TagProvider;
 use TypeLang\PHPDoc\Tag\TagProviderInterface;
 
 /**
- * @template-implements \IteratorAggregate<int<0, max>, Tag>
- * @template-implements \ArrayAccess<int<0, max>, Tag|null>
+ * This class represents structure containing a description and a set of tags
+ * that describe an arbitrary DocBlock Comment in the code.
+ *
+ * @template-implements \IteratorAggregate<int<0, max>, TagInterface>
+ * @template-implements \ArrayAccess<int<0, max>, TagInterface|null>
  */
 final class DocBlock implements
+    DescriptionProviderInterface,
     TagProviderInterface,
     \IteratorAggregate,
     \ArrayAccess
 {
     use TagProvider;
 
+    private readonly DescriptionInterface $description;
+
     /**
-     * @param iterable<array-key, Tag> $tags
+     * @param iterable<array-key, TagInterface> $tags List of all tags contained in
+     *        a docblock object.
+     *
+     *        Note that the constructor can receive an arbitrary iterator, like
+     *        {@see \Traversable} or {@see array}, but the object itself
+     *        contains the directly generated list ({@see array}} of
+     *        {@see TagInterface} objects.
      */
     public function __construct(
-        private readonly Description $description = new Description(),
+        string|\Stringable $description = '',
         iterable $tags = [],
     ) {
+        $this->description = Description::fromStringable($description);
+
         $this->bootTagProvider($tags);
     }
 
@@ -35,7 +51,7 @@ public function offsetExists(mixed $offset): bool
         return isset($this->tags[$offset]);
     }
 
-    public function offsetGet(mixed $offset): ?Tag
+    public function offsetGet(mixed $offset): ?TagInterface
     {
         return $this->tags[$offset] ?? null;
     }
@@ -50,7 +66,7 @@ public function offsetUnset(mixed $offset): void
         throw new \BadMethodCallException(self::class . ' objects are immutable');
     }
 
-    public function getDescription(): Description
+    public function getDescription(): DescriptionInterface
     {
         return $this->description;
     }
diff --git a/src/Parser.php b/src/Parser.php
@@ -15,8 +15,8 @@
 use TypeLang\PHPDoc\Parser\SourceMap;
 use TypeLang\PHPDoc\Parser\Tag\TagParser;
 use TypeLang\PHPDoc\Parser\Tag\TagParserInterface;
-use TypeLang\PHPDoc\Tag\TagFactory;
-use TypeLang\PHPDoc\Tag\FactoryInterface;
+use TypeLang\PHPDoc\Tag\Factory\FactoryInterface;
+use TypeLang\PHPDoc\Tag\Factory\TagFactory;
 
 /**
  * @psalm-suppress UndefinedAttributeClass : JetBrains language attribute may not be available
diff --git a/src/Parser/Description/DescriptionParserInterface.php b/src/Parser/Description/DescriptionParserInterface.php
@@ -4,7 +4,7 @@
 
 namespace TypeLang\PHPDoc\Parser\Description;
 
-use TypeLang\PHPDoc\Tag\Description;
+use TypeLang\PHPDoc\Tag\DescriptionInterface;
 
 interface DescriptionParserInterface
 {
@@ -25,5 +25,5 @@ interface DescriptionParserInterface
      * // }
      * ```
      */
-    public function parse(string $description): Description;
+    public function parse(string $description): DescriptionInterface;
 }
diff --git a/src/Parser/Tag/TagParser.php b/src/Parser/Tag/TagParser.php
@@ -7,8 +7,9 @@
 use TypeLang\PHPDoc\Exception\InvalidTagNameException;
 use TypeLang\PHPDoc\Exception\RuntimeExceptionInterface;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
-use TypeLang\PHPDoc\Tag\FactoryInterface;
+use TypeLang\PHPDoc\Tag\Factory\FactoryInterface;
 use TypeLang\PHPDoc\Tag\Tag;
+use TypeLang\PHPDoc\Tag\TagInterface;
 
 final class TagParser implements TagParserInterface
 {
@@ -63,7 +64,7 @@ private function getTagName(string $content): string
      * @throws \Throwable
      * @throws RuntimeExceptionInterface
      */
-    public function parse(string $tag, DescriptionParserInterface $parser): Tag
+    public function parse(string $tag, DescriptionParserInterface $parser): TagInterface
     {
         $name = $this->getTagName($tag);
         /** @var non-empty-string $name */
diff --git a/src/Parser/Tag/TagParserInterface.php b/src/Parser/Tag/TagParserInterface.php
@@ -5,7 +5,7 @@
 namespace TypeLang\PHPDoc\Parser\Tag;
 
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
-use TypeLang\PHPDoc\Tag\Tag;
+use TypeLang\PHPDoc\Tag\TagInterface;
 
 interface TagParserInterface
 {
@@ -24,5 +24,5 @@ interface TagParserInterface
      * // }
      * ```
      */
-    public function parse(string $tag, DescriptionParserInterface $parser): Tag;
+    public function parse(string $tag, DescriptionParserInterface $parser): TagInterface;
 }
diff --git a/src/Tag/Description.php b/src/Tag/Description.php
@@ -5,19 +5,16 @@
 namespace TypeLang\PHPDoc\Tag;
 
 /**
- * @template-implements \IteratorAggregate<int<0, max>, Tag>
+ * @template-implements \IteratorAggregate<int<0, max>, TagInterface>
  */
-class Description implements
-    TagProviderInterface,
-    \IteratorAggregate,
-    \Stringable
+class Description implements DescriptionInterface, \IteratorAggregate
 {
     use TagProvider;
 
-    private readonly string $template;
+    protected readonly string $template;
 
     /**
-     * @param iterable<array-key, Tag> $tags
+     * @param iterable<array-key, TagInterface> $tags
      */
     public function __construct(
         string|\Stringable $template = '',
@@ -28,38 +25,29 @@ public function __construct(
         $this->bootTagProvider($tags);
     }
 
-    public static function fromString(string|\Stringable $description): self
+    public static function fromStringable(string|\Stringable $description): DescriptionInterface
     {
-        if ($description instanceof self) {
+        if ($description instanceof DescriptionInterface) {
             return $description;
         }
 
         return new self($description);
     }
 
-    public static function fromStringOrNull(string|\Stringable|null $description): ?self
+    public static function fromStringableOrNull(string|\Stringable|null $description): ?DescriptionInterface
     {
         if ($description === null) {
             return null;
         }
 
-        return self::fromString($description);
+        return self::fromStringable($description);
     }
 
-    /**
-     * Returns the body template.
-     *
-     * @api
-     * @psalm-immutable
-     */
     public function getTemplate(): string
     {
         return $this->template;
     }
 
-    /**
-     * @psalm-immutable
-     */
     public function __toString(): string
     {
         $tags = [];
diff --git a/src/Tag/DescriptionInterface.php b/src/Tag/DescriptionInterface.php
@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Tag;
+
+interface DescriptionInterface extends TagProviderInterface, \Stringable
+{
+    /**
+     * Returns the body template.
+     *
+     * @psalm-immutable Each call to the method must return the same value.
+     */
+    public function getTemplate(): string;
+
+    /**
+     * Returns a plain string representation of this description.
+     *
+     * Magic method {@link https://www.php.net/manual/en/language.oop5.magic.php#object.tostring}
+     * allows a class to decide how it will react when it is treated like
+     * a string.
+     *
+     * @psalm-immutable Each call to the method must return the same value.
+     */
+    public function __toString(): string;
+}
diff --git a/src/Tag/DescriptionProviderInterface.php b/src/Tag/DescriptionProviderInterface.php
@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Tag;
+
+interface DescriptionProviderInterface
+{
+    /**
+     * 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;
+}
diff --git a/src/Tag/Factory/FactoryInterface.php b/src/Tag/Factory/FactoryInterface.php
@@ -2,10 +2,11 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PHPDoc\Tag;
+namespace TypeLang\PHPDoc\Tag\Factory;
 
 use TypeLang\PHPDoc\Exception\RuntimeExceptionInterface;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
+use TypeLang\PHPDoc\Tag\TagInterface;
 
 interface FactoryInterface
 {
@@ -17,5 +18,5 @@ interface FactoryInterface
      * @throws RuntimeExceptionInterface In case of parsing error occurs.
      * @throws \Throwable In case of internal error occurs.
      */
-    public function create(string $name, string $content, DescriptionParserInterface $descriptions): Tag;
+    public function create(string $name, string $content, DescriptionParserInterface $descriptions): TagInterface;
 }
diff --git a/src/Tag/Factory/MutableFactoryInterface.php b/src/Tag/Factory/MutableFactoryInterface.php
@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\Tag\Factory;
+
+interface MutableFactoryInterface extends FactoryInterface
+{
+    /**
+     * Registers a handler for tags.
+     *
+     * If you want to use your own tags then you can use this method to
+     * instruct the {@see FactoryInterface} to register the name of a tag with
+     * the custom {@see FactoryInterface} to which processing of this tag will
+     * be delegated.
+     *
+     * @param non-empty-string|list<non-empty-string> $tags
+     */
+    public function register(string|array $tags, FactoryInterface $delegate): void;
+}
diff --git a/src/Tag/Factory/PrefixedTagFactory.php b/src/Tag/Factory/PrefixedTagFactory.php
@@ -2,9 +2,10 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PHPDoc\Tag;
+namespace TypeLang\PHPDoc\Tag\Factory;
 
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
+use TypeLang\PHPDoc\Tag\TagInterface;
 
 final class PrefixedTagFactory implements MutableFactoryInterface
 {
@@ -25,7 +26,7 @@ public function register(array|string $tags, FactoryInterface $delegate): void
         }
     }
 
-    public function create(string $name, string $content, DescriptionParserInterface $descriptions): Tag
+    public function create(string $name, string $content, DescriptionParserInterface $descriptions): TagInterface
     {
         return $this->delegate->create($name, $content, $descriptions);
     }
diff --git a/src/Tag/Factory/TagFactory.php b/src/Tag/Factory/TagFactory.php
@@ -2,12 +2,14 @@
 
 declare(strict_types=1);
 
-namespace TypeLang\PHPDoc\Tag;
+namespace TypeLang\PHPDoc\Tag\Factory;
 
 use TypeLang\PHPDoc\Exception\InvalidTagException;
 use TypeLang\PHPDoc\Exception\ParsingException;
 use TypeLang\PHPDoc\Exception\RuntimeExceptionInterface;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
+use TypeLang\PHPDoc\Tag\Tag;
+use TypeLang\PHPDoc\Tag\TagInterface;
 
 final class TagFactory implements MutableFactoryInterface
 {
@@ -25,7 +27,7 @@ public function register(array|string $tags, FactoryInterface $delegate): void
         }
     }
 
-    public function create(string $name, string $content, DescriptionParserInterface $descriptions): Tag
+    public function create(string $name, string $content, DescriptionParserInterface $descriptions): TagInterface
     {
         $delegate = $this->factories[$name] ?? null;
 
diff --git a/src/Tag/MutableFactoryInterface.php b/src/Tag/MutableFactoryInterface.php
diff --git a/src/Tag/Tag.php b/src/Tag/Tag.php
@@ -4,9 +4,9 @@
 
 namespace TypeLang\PHPDoc\Tag;
 
-class Tag implements \Stringable
+class Tag implements TagInterface
 {
-    protected readonly ?Description $description;
+    protected readonly ?DescriptionInterface $description;
 
     /**
      * @param non-empty-string $name
@@ -15,39 +15,19 @@ public function __construct(
         protected readonly string $name,
         \Stringable|string|null $description = null,
     ) {
-        $this->description = Description::fromStringOrNull($description);
+        $this->description = Description::fromStringableOrNull($description);
     }
 
-    /**
-     * @return non-empty-string
-     *
-     * @psalm-immutable
-     */
     public function getName(): string
     {
         return $this->name;
     }
 
-    /**
-     * Returns description of the tag.
-     *
-     * @psalm-immutable
-     */
-    public function getDescription(): ?Description
+    public function getDescription(): ?DescriptionInterface
     {
         return $this->description;
     }
 
-    /**
-     * Magic method {@link https://www.php.net/manual/en/language.oop5.magic.php#object.tostring}
-     * allows a class to decide how it will react when it is treated like
-     * a string.
-     *
-     * @psalm-immutable
-     * @return string Returns string representation of the object that
-     *         implements this interface (and/or {@see __toString()} magic
-     *         method).
-     */
     public function __toString(): string
     {
         if ($this->description === null) {
diff --git a/src/Tag/TagInterface.php b/src/Tag/TagInterface.php
diff --git a/src/Tag/TagProvider.php b/src/Tag/TagProvider.php
diff --git a/src/Tag/TagProviderInterface.php b/src/Tag/TagProviderInterface.php
diff --git a/src/Tag/TypeProviderInterface.php b/src/Tag/TypeProviderInterface.php
diff --git a/src/Tag/TypedTag.php b/src/Tag/TypedTag.php

Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@`
`4`	`4`
`5`	`5`	`namespace TypeLang\PHPDoc\Parser\Description;`
`6`	`6`
`7`		`-use TypeLang\PHPDoc\Tag\Description;`
	`7`	`+use TypeLang\PHPDoc\Tag\DescriptionInterface;`
`8`	`8`
`9`	`9`	`interface DescriptionParserInterface`
`10`	`10`	`{`
`@@ -25,5 +25,5 @@ interface DescriptionParserInterface`
`25`	`25`	`* // }`
`26`	`26`	* ```
`27`	`27`	`*/`
`28`		`- public function parse(string $description): Description;`
	`28`	`+ public function parse(string $description): DescriptionInterface;`
`29`	`29`	`}`
Original file line number	Diff line number	Diff line change
`@@ -5,7 +5,7 @@`
`5`	`5`	`namespace TypeLang\PHPDoc\Parser\Tag;`
`6`	`6`
`7`	`7`	`use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;`
`8`		`-use TypeLang\PHPDoc\Tag\Tag;`
	`8`	`+use TypeLang\PHPDoc\Tag\TagInterface;`
`9`	`9`
`10`	`10`	`interface TagParserInterface`
`11`	`11`	`{`
`@@ -24,5 +24,5 @@ interface TagParserInterface`
`24`	`24`	`* // }`
`25`	`25`	* ```
`26`	`26`	`*/`
`27`		`- public function parse(string $tag, DescriptionParserInterface $parser): Tag;`
	`27`	`+ public function parse(string $tag, DescriptionParserInterface $parser): TagInterface;`
`28`	`28`	`}`
Original file line number	Diff line number	Diff line change
`@@ -5,19 +5,16 @@`
`5`	`5`	`namespace TypeLang\PHPDoc\Tag;`
`6`	`6`
`7`	`7`	`/**`
`8`		`- * @template-implements \IteratorAggregate<int<0, max>, Tag>`
	`8`	`+ * @template-implements \IteratorAggregate<int<0, max>, TagInterface>`
`9`	`9`	`*/`
`10`		`-class Description implements`
`11`		`- TagProviderInterface,`
`12`		`- \IteratorAggregate,`
`13`		`- \Stringable`
	`10`	`+class Description implements DescriptionInterface, \IteratorAggregate`
`14`	`11`	`{`
`15`	`12`	`use TagProvider;`
`16`	`13`
`17`		`- private readonly string $template;`
	`14`	`+ protected readonly string $template;`
`18`	`15`
`19`	`16`	`/**`
`20`		`- * @param iterable<array-key, Tag> $tags`
	`17`	`+ * @param iterable<array-key, TagInterface> $tags`
`21`	`18`	`*/`
`22`	`19`	`public function __construct(`
`23`	`20`	`string\|\Stringable $template = '',`
`@@ -28,38 +25,29 @@ public function __construct(`
`28`	`25`	`$this->bootTagProvider($tags);`
`29`	`26`	`}`
`30`	`27`
`31`		`- public static function fromString(string\|\Stringable $description): self`
	`28`	`+ public static function fromStringable(string\|\Stringable $description): DescriptionInterface`
`32`	`29`	`{`
`33`		`- if ($description instanceof self) {`
	`30`	`+ if ($description instanceof DescriptionInterface) {`
`34`	`31`	`return $description;`
`35`	`32`	`}`
`36`	`33`
`37`	`34`	`return new self($description);`
`38`	`35`	`}`
`39`	`36`
`40`		`- public static function fromStringOrNull(string\|\Stringable\|null $description): ?self`
	`37`	`+ public static function fromStringableOrNull(string\|\Stringable\|null $description): ?DescriptionInterface`
`41`	`38`	`{`
`42`	`39`	`if ($description === null) {`
`43`	`40`	`return null;`
`44`	`41`	`}`
`45`	`42`
`46`		`- return self::fromString($description);`
	`43`	`+ return self::fromStringable($description);`
`47`	`44`	`}`
`48`	`45`
`49`		`- /**`
`50`		`- * Returns the body template.`
`51`		`- *`
`52`		`- * @api`
`53`		`- * @psalm-immutable`
`54`		`- */`
`55`	`46`	`public function getTemplate(): string`
`56`	`47`	`{`
`57`	`48`	`return $this->template;`
`58`	`49`	`}`
`59`	`50`
`60`		`- /**`
`61`		`- * @psalm-immutable`
`62`		`- */`
`63`	`51`	`public function __toString(): string`
`64`	`52`	`{`
`65`	`53`	`$tags = [];`