Add "@api" and "@psalm-api" tags support

Author: Kirill Nesmeyanov

README.md

@@ -33,7 +33,7 @@ composer require type-lang/phpdoc
 ## Supported Tags
 
 - [x] `@abstract` - Declare any _Symbol_ as abstract
-- [ ] `@api` - TODO
+- [x] `@api` - Highlight _Symbol_ as being part of the public API
 - [ ] `@author` - TODO
 - [ ] `@category` - TODO
 - [ ] `@copyright` - TODO
@@ -103,7 +103,7 @@ composer require type-lang/phpdoc
 ### Psalm Tags
 
 - [ ] `@psalm-allow-private-mutation` - TODO
-- [ ] `@psalm-api` - TODO
+- [x] `@psalm-api` - Vendor-specific `@api` alias
 - [ ] `@psalm-assert` - TODO
 - [ ] `@psalm-assert-if-false` - TODO
 - [ ] `@psalm-assert-if-true` - TODO

src/DocBlock/Tag/ApiTag/ApiTag.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Tag\ApiTag;
+
+use TypeLang\PHPDoc\DocBlock\Tag\Tag;
+
+/**
+ * Used to highlight _Symbol_ as being part of the primary
+ * public API of a package.
+ *
+ * The "`@api`" tag may be applied to public _Symbol_ to highlight them
+ * in generated documentation, pointing the consumer to the primary public
+ * API components of a library or framework.
+ *
+ * When the "`@api`" tag is used, other _Symbol_ with a public
+ * visibility serve to support the internal structure and
+ * are not recommended to be used by the consumer.
+ *
+ * The exact meaning of _Symbol_ tagged with "`@api`" MAY differ per project.
+ * It is however RECOMMENDED that all "`@api`" tagged _Symbol_ SHOULD
+ * NOT change after publication unless the new version
+ * is tagged as breaking Backwards Compatibility.
+ *
+ * See also the `"@internal"` tag, which can be used to hide internal
+ * _Symbol_ from generated documentation.
+ *
+ * ```
+ * "@api" [<description>]
+ * ```
+ */
+final class ApiTag extends Tag
+{
+    public function __construct(
+        string $name,
+        \Stringable|string|null $description = null,
+    ) {
+        parent::__construct($name, $description);
+    }
+}

src/DocBlock/Tag/ApiTag/ApiTagFactory.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Tag\ApiTag;
+
+use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
+use TypeLang\PHPDoc\Parser\Content\Stream;
+use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
+
+/**
+ * This class is responsible for creating "`@api`" tags.
+ *
+ * See {@see ApiTag} for details about this tag.
+ */
+final class ApiTagFactory implements TagFactoryInterface
+{
+    public function create(string $tag, string $content, DescriptionParserInterface $descriptions): ApiTag
+    {
+        $stream = new Stream($tag, $content);
+
+        return new ApiTag(
+            name: $tag,
+            description: $stream->toOptionalDescription($descriptions),
+        );
+    }
+}

src/Platform/PsalmPlatform.php

@@ -5,6 +5,7 @@
 namespace TypeLang\PHPDoc\Platform;
 
 use TypeLang\Parser\ParserInterface as TypesParserInterface;
+use TypeLang\PHPDoc\DocBlock\Tag\ApiTag\ApiTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\MethodTag\MethodTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\ParamTag\ParamTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\PropertyTag\PropertyReadTagFactory;
@@ -27,6 +28,7 @@ public function getName(): string
 
     protected function load(TypesParserInterface $types): iterable
     {
+        yield 'psalm-api' => new ApiTagFactory();
         yield 'psalm-method' => new MethodTagFactory($types);
         yield 'psalm-param' => new ParamTagFactory($types);
         yield 'psalm-property' => new PropertyTagFactory($types);

src/Platform/StandardPlatform.php

@@ -6,6 +6,7 @@
 
 use TypeLang\Parser\ParserInterface as TypesParserInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\AbstractTag\AbstractTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\ApiTag\ApiTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\FinalTag\FinalTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\IgnoreTag\IgnoreTagFactory;
@@ -38,6 +39,7 @@ public function getName(): string
     protected function load(TypesParserInterface $types): iterable
     {
         yield 'abstract' => new AbstractTagFactory();
+        yield 'api' => new ApiTagFactory();
         yield 'extends' => new TemplateExtendsTagFactory($types);
         yield 'final' => new FinalTagFactory();
         yield 'implements' => new TemplateImplementsTagFactory($types);