Add "@category" tag support

Author: SerafimArts

README.md

@@ -35,7 +35,7 @@ composer require type-lang/phpdoc
 - [x] `@abstract` - Declare any _Element_ as abstract
 - [x] `@api` - Highlight _Element_ as being part of the public API
 - [ ] `@author` - TODO
-- [ ] `@category` - TODO
+- [x] `@category` - Used to organize groups of packages together
 - [x] `@copyright` - Used to document the copyright information of any _Element_.
 - [ ] `@deprecated` - TODO
 - [ ] `@example` - TODO

src/DocBlock/Tag/CategoryTag/CategoryTag.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Tag\CategoryTag;
+
+use TypeLang\PHPDoc\DocBlock\Tag\Tag;
+
+/**
+ * Used to organize groups of packages together.
+ *
+ * The "`@category`" tag was meant in the original de-facto Standard to group
+ * several _Elements_ by their "`@package`" tags into one category.
+ * These categories could then be used to aid in the
+ * generation of API documentation.
+ *
+ * This was necessary since the "`@package`" tag, as defined in the
+ * original Standard, did not allow for more than one hierarchy
+ * level. Since this has changed this tag SHOULD NOT be used.
+ *
+ * Please see the documentation for "`@package`" for details of its usage.
+ *
+ * ```
+ * "@category" [<description>]
+ * ```
+ */
+final class CategoryTag extends Tag
+{
+    public function __construct(
+        string $name,
+        \Stringable|string|null $description = null,
+    ) {
+        parent::__construct($name, $description);
+    }
+}

src/DocBlock/Tag/CategoryTag/CategoryTagFactory.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Tag\CategoryTag;
+
+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 "`@category`" tags.
+ *
+ * See {@see CategoryTag} for details about this tag.
+ */
+final class CategoryTagFactory implements TagFactoryInterface
+{
+    public function create(string $tag, string $content, DescriptionParserInterface $descriptions): CategoryTag
+    {
+        $stream = new Stream($tag, $content);
+
+        return new CategoryTag(
+            name: $tag,
+            description: $stream->toOptionalDescription($descriptions),
+        );
+    }
+}

src/DocBlock/Tag/SeeTag/SeeTag.php

@@ -4,8 +4,8 @@
 
 namespace TypeLang\PHPDoc\DocBlock\Tag\SeeTag;
 
-use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ReferenceInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ElementReference;
+use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ReferenceInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\UriReference;
 use TypeLang\PHPDoc\DocBlock\Tag\Tag;
 

src/DocBlock/Tag/SeeTag/SeeTagFactory.php

@@ -7,8 +7,8 @@
 use TypeLang\Parser\Parser as TypesParser;
 use TypeLang\Parser\ParserInterface as TypesParserInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
-use TypeLang\PHPDoc\Parser\Content\Stream;
 use TypeLang\PHPDoc\Parser\Content\ElementReferenceReader;
+use TypeLang\PHPDoc\Parser\Content\Stream;
 use TypeLang\PHPDoc\Parser\Content\UriReferenceReader;
 use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
 

src/Parser/Content/ElementReferenceReader.php

@@ -12,8 +12,8 @@
 use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ClassConstantElementReference;
 use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ClassMethodElementReference;
 use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ClassPropertyElementReference;
-use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\FunctionReference;
 use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\ElementReference;
+use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\FunctionReference;
 use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\TypeElementReference;
 use TypeLang\PHPDoc\DocBlock\Tag\Shared\Reference\VariableReference;
 

src/Platform/StandardPlatform.php

@@ -7,6 +7,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\CategoryTag\CategoryTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\CopyrightTag\CopyrightTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
 use TypeLang\PHPDoc\DocBlock\Tag\FinalTag\FinalTagFactory;
@@ -42,6 +43,7 @@ protected function load(TypesParserInterface $types): iterable
     {
         yield 'abstract' => new AbstractTagFactory();
         yield 'api' => new ApiTagFactory();
+        yield 'category' => new CategoryTagFactory();
         yield 'copyright' => new CopyrightTagFactory();
         yield 'extends' => new TemplateExtendsTagFactory($types);
         yield 'final' => new FinalTagFactory();