Improve psalm annotations and replace description tags constructor to the factory

Author: Kirill Nesmeyanov

src/DocBlock/Description.php

@@ -27,12 +27,17 @@ public static function create(string $body): self
 
     /**
      * Returns the body template.
+     *
+     * @psalm-immutable
      */
     public function getBodyTemplate(): string
     {
         return $this->bodyTemplate;
     }
 
+    /**
+     * @psalm-immutable
+     */
     public function __toString(): string
     {
         /** @psalm-suppress ImplicitToStringCast */

src/DocBlock/Extractor/TagNameExtractor.php

@@ -21,8 +21,8 @@ final class TagNameExtractor
      *   - "@tag With\TypeName $andVariableName And description"
      *   - etc...
      *
+     * @psalm-immutable
      * @return list{non-empty-string, non-empty-string|null}
-     *
      * @throws \Throwable
      */
     public function extract(string $body): array
@@ -48,8 +48,8 @@ public function extract(string $body): array
     }
 
     /**
+     * @psalm-immutable
      * @return list{non-empty-string, non-empty-string|null}
-     *
      * @throws \Throwable
      */
     private function createFromNamed(string $body, int $offset): array
@@ -70,10 +70,9 @@ private function createFromNamed(string $body, int $offset): array
     }
 
     /**
+     * @psalm-immutable
      * @param non-empty-string $tag
-     *
      * @return list{non-empty-string, null}
-     *
      * @throws \Throwable
      */
     private function createFromBodiless(string $body): array

src/DocBlock/Extractor/TagTypeExtractor.php

@@ -21,8 +21,8 @@ public function __construct(
     ) {}
 
     /**
+     * @psalm-immutable
      * @return array{TypeStatement, non-empty-string|null}
-     *
      * @throws InvalidTagTypeException
      */
     public function extractTypeOrFail(string $body): array

src/DocBlock/Extractor/TagVariableExtractor.php

@@ -9,6 +9,7 @@
 final class TagVariableExtractor
 {
     /**
+     * @psalm-immutable
      * @return array{non-empty-string|null, non-empty-string|null}
      */
     public function extractOrNull(?string $body): array
@@ -34,6 +35,7 @@ public function extractOrNull(?string $body): array
     }
 
     /**
+     * @psalm-immutable
      * @return array{non-empty-string, non-empty-string|null}
      */
     public function extractOrFail(?string $body): array

src/DocBlock/Tag/ApiTag.php

@@ -4,11 +4,9 @@
 
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
-use TypeLang\PhpDocParser\DocBlock\Description;
-
 final class ApiTag extends Tag
 {
-    public function __construct(Description|string|null $description = null)
+    public function __construct(\Stringable|string|null $description = null)
     {
         parent::__construct('api', $description);
     }

src/DocBlock/Tag/AuthorTag.php

@@ -4,11 +4,9 @@
 
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
-use TypeLang\PhpDocParser\DocBlock\Description;
-
 final class AuthorTag extends Tag
 {
-    public function __construct(Description|string|null $description = null)
+    public function __construct(\Stringable|string|null $description = null)
     {
         parent::__construct('author', $description);
     }

src/DocBlock/Tag/CopyrightTag.php

@@ -4,11 +4,9 @@
 
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
-use TypeLang\PhpDocParser\DocBlock\Description;
-
 final class CopyrightTag extends Tag
 {
-    public function __construct(Description|string|null $description = null)
+    public function __construct(\Stringable|string|null $description = null)
     {
         parent::__construct('copyright', $description);
     }

src/DocBlock/Tag/DeprecatedTag.php

@@ -4,14 +4,12 @@
 
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
-use TypeLang\PhpDocParser\DocBlock\Description;
-
 /**
  * TODO Add version support: {@link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/deprecated.html#deprecated}
  */
 final class DeprecatedTag extends Tag
 {
-    public function __construct(Description|string|null $description = null)
+    public function __construct(\Stringable|string|null $description = null)
     {
         parent::__construct('deprecated', $description);
     }

src/DocBlock/Tag/ExampleTag.php

@@ -4,14 +4,12 @@
 
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
-use TypeLang\PhpDocParser\DocBlock\Description;
-
 /**
  * TODO Add location support: {@link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/example.html#example}
  */
 final class ExampleTag extends Tag
 {
-    public function __construct(Description|string|null $description = null)
+    public function __construct(\Stringable|string|null $description = null)
     {
         parent::__construct('example', $description);
     }

src/DocBlock/Tag/FilesourceTag.php

@@ -4,11 +4,9 @@
 
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
-use TypeLang\PhpDocParser\DocBlock\Description;
-
 final class FilesourceTag extends Tag
 {
-    public function __construct(Description|string|null $description = null)
+    public function __construct(\Stringable|string|null $description = null)
     {
         parent::__construct('filesource', $description);
     }