Reorganize and improve supported tags

Author: Kirill Nesmeyanov

src/DocBlock/Tag/ApiTag.php

@@ -4,10 +4,21 @@
 
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
-final class ApiTag extends Tag
+/**
+ * TODO This tag doesnt support description: Should support for this
+ *      functionality be removed?
+ *
+ * @link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/api.html#api
+ */
+final class ApiTag extends Tag implements CreatableFromDescriptionInterface
 {
     public function __construct(\Stringable|string|null $description = null)
     {
         parent::__construct('api', $description);
     }
+
+    public static function createFromDescription(\Stringable|string|null $description = null): self
+    {
+        return new self($description);
+    }
 }

src/DocBlock/Tag/AuthorTag.php

@@ -4,10 +4,21 @@
 
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
-final class AuthorTag extends Tag
+/**
+ * TODO Replace description to required "name" string scalar.
+ * TODO Add email parsing support.
+ *
+ * @link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/author.html#author
+ */
+final class AuthorTag extends Tag implements CreatableFromDescriptionInterface
 {
     public function __construct(\Stringable|string|null $description = null)
     {
         parent::__construct('author', $description);
     }
+
+    public static function createFromDescription(\Stringable|string|null $description = null): self
+    {
+        return new self($description);
+    }
 }

src/DocBlock/Tag/CategoryTag.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDocParser\DocBlock\Tag;
+
+/**
+ * TODO Replace description to simple string scalar.
+ *
+ * @link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/category.html#category
+ */
+final class CategoryTag extends Tag implements CreatableFromDescriptionInterface
+{
+    public function __construct(\Stringable|string|null $description = null)
+    {
+        parent::__construct('category', $description);
+    }
+
+    public static function createFromDescription(\Stringable|string|null $description = null): self
+    {
+        return new self($description);
+    }
+}

src/DocBlock/Tag/CopyrightTag.php

@@ -4,10 +4,18 @@
 
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
-final class CopyrightTag extends Tag
+/**
+ * @link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/copyright.html#copyright
+ */
+final class CopyrightTag extends Tag implements CreatableFromDescriptionInterface
 {
     public function __construct(\Stringable|string|null $description = null)
     {
         parent::__construct('copyright', $description);
     }
+
+    public static function createFromDescription(\Stringable|string|null $description = null): self
+    {
+        return new self($description);
+    }
 }

src/DocBlock/Tag/CreatableFromDescriptionInterface.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDocParser\DocBlock\Tag;
+
+interface CreatableFromDescriptionInterface extends TagInterface
+{
+    /**
+     * Creates a new tag instance from an arbitrary optional string-like argument.
+     */
+    public static function createFromDescription(\Stringable|string|null $description = null): self;
+}

src/DocBlock/Tag/CreatableFromNameTypeAndDescriptionInterface.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDocParser\DocBlock\Tag;
+
+use TypeLang\Parser\Node\Stmt\TypeStatement;
+
+interface CreatableFromNameTypeAndDescriptionInterface extends
+    TagInterface,
+    TypeProviderInterface,
+    VariableNameProviderInterface
+{
+    /**
+     * Creates a new tag instance from required "name" identifier, required
+     * {@see TypeStatement} type statement and arbitrary optional
+     * string-like description arguments.
+     *
+     * @param non-empty-string $name
+     */
+    public static function createFromNameTypeAndDescription(
+        string $name,
+        TypeStatement $type,
+        \Stringable|string|null $description = null,
+    ): self;
+}

src/DocBlock/Tag/CreatableFromTagAndDescriptionInterface.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDocParser\DocBlock\Tag;
+
+use TypeLang\Parser\Node\Stmt\TypeStatement;
+
+interface CreatableFromTagAndDescriptionInterface extends TagInterface, TypeProviderInterface
+{
+    /**
+     * Creates a new tag instance from a required {@see TypeStatement} type
+     * statement and arbitrary optional string-like description argument.
+     */
+    public static function createFromTagAndDescription(
+        TypeStatement $type,
+        \Stringable|string|null $description = null,
+    ): self;
+}

src/DocBlock/Tag/DeprecatedTag.php

@@ -5,12 +5,19 @@
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
 /**
- * TODO Add version support: {@link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/deprecated.html#deprecated}
+ * TODO Add semantic versioning prefix support.
+ *
+ * @link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/deprecated.html#deprecated
  */
-final class DeprecatedTag extends Tag
+final class DeprecatedTag extends Tag implements CreatableFromDescriptionInterface
 {
     public function __construct(\Stringable|string|null $description = null)
     {
         parent::__construct('deprecated', $description);
     }
+
+    public static function createFromDescription(\Stringable|string|null $description = null): self
+    {
+        return new self($description);
+    }
 }

src/DocBlock/Tag/ExampleTag.php

@@ -5,12 +5,21 @@
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
 /**
- * TODO Add location support: {@link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/example.html#example}
+ * TODO Add required location support
+ * TODO Add optional start line support
+ * TODO Add optional number of lines support
+ *
+ * @link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/example.html#example
  */
-final class ExampleTag extends Tag
+final class ExampleTag extends Tag implements CreatableFromDescriptionInterface
 {
     public function __construct(\Stringable|string|null $description = null)
     {
         parent::__construct('example', $description);
     }
+
+    public static function createFromDescription(\Stringable|string|null $description = null): self
+    {
+        return new self($description);
+    }
 }

src/DocBlock/Tag/FilesourceTag.php

@@ -4,10 +4,21 @@
 
 namespace TypeLang\PhpDocParser\DocBlock\Tag;
 
-final class FilesourceTag extends Tag
+/**
+ * TODO This tag doesnt support description: Should support for this
+ *      functionality be removed?
+ *
+ * @link https://docs.phpdoc.org/3.0/guide/references/phpdoc/tags/filesource.html#filesource
+ */
+final class FilesourceTag extends Tag implements CreatableFromDescriptionInterface
 {
     public function __construct(\Stringable|string|null $description = null)
     {
         parent::__construct('filesource', $description);
     }
+
+    public static function createFromDescription(\Stringable|string|null $description = null): self
+    {
+        return new self($description);
+    }
 }