Add "@Package" and "@subpackage" tags support

Author: SerafimArts

README.md

@@ -56,7 +56,7 @@ composer require type-lang/phpdoc
 - [ ] `@mixin` - TODO
 - [x] `@no-named-arguments` - Indicates that argument names may be 
       changed in the future.
-- [ ] `@package` - TODO
+- [x] `@package` - Used to categorize _Element(s)_ into logical subdivisions
 - [x] `@override` - Mention to see if the method is actually overriding a definition
 - [x] `@param` - Used to document a single argument of a function or method
 - [ ] `@param-closure-this` - TODO
@@ -78,7 +78,7 @@ composer require type-lang/phpdoc
       website or other _Symbol(s)_
 - [ ] `@since` - TODO
 - [ ] `@source` - TODO
-- [ ] `@subpackage` - TODO
+- [x] `@subpackage` - Used to categorize _Element(s)_ into logical subdivisions
 - [ ] `@suppress` - TODO
 - [x] `@template` - Allows classes (and class-like entries), functions and
       methods to declare a generic type parameter

src/DocBlock/Tag/MethodTag/MethodTag.php

@@ -36,9 +36,9 @@
  * with a class or interface.
  *
  * ```
- * "@method" [static] <CallableType> [<description>]
- * "@method" [static] <ReturnType> <CallableType> [<description>]
- * "@method" [static] <CallableType>: <ReturnType> [<description>]
+ * "@method" [static] <callable-type> [<description>]
+ * "@method" [static] <return-type> <callable-type> [<description>]
+ * "@method" [static] <callable-type>: <return-type> [<description>]
  * ```
  */
 class MethodTag extends Tag implements OptionalTypeProviderInterface

src/DocBlock/Tag/PackageTag/PackageTag.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Tag\PackageTag;
+
+use TypeLang\PHPDoc\DocBlock\Tag\Tag;
+
+/**
+ * Used to categorize _Element(s)_ into logical subdivisions.
+ *
+ * The "`@package`" tag can be used as a counterpart or supplement to
+ * Namespaces. Namespaces provide a functional subdivision of _Element(s)_
+ * where the "`@package`" tag can provide a logical subdivision in which
+ * way the elements can be grouped with a different hierarchy.
+ *
+ * If, across the board, both logical and functional subdivisions
+ * are equal is it NOT RECOMMENDED to use the "`@package`"
+ * tag to prevent maintenance overhead.
+ *
+ * Each level in the logical hierarchy MUST be separated with a backslash
+ * (`\`) to be familiar to Namespaces. A hierarchy MAY be of endless depth
+ * but it is RECOMMENDED to keep the depth at less or equal than six levels.
+ *
+ * Please note that the "`@package`" tag applies to different _Element(s)_
+ * depending where it is defined.
+ *
+ * - If the package is defined in the file-level DocBlock then it only applies
+ *   to the following elements in the applicable file:
+ *    - global functions
+ *    - global constants
+ *    - global variables
+ *    - requires and includes
+ *
+ * - If the package is defined in a namespace-level or class-level DocBlock
+ *   then the package applies to that namespace, class, trait or interface
+ *   and their contained elements. This means that a function which is
+ *   contained in a namespace with the "`@package`" tag assumes that package.
+ *
+ * The "`@package`" tag MUST NOT occur more than once in a PHPDoc.
+ *
+ * ```
+ * "@package" <namespace> [<description>]
+ * ```
+ */
+final class PackageTag extends SubPackageTag {}

src/DocBlock/Tag/PackageTag/PackageTagFactory.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Tag\PackageTag;
+
+use TypeLang\Parser\Parser as TypesParser;
+use TypeLang\Parser\ParserInterface as TypesParserInterface;
+use TypeLang\PHPDoc\DocBlock\Tag\Factory\TagFactoryInterface;
+use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
+
+/**
+ * This class is responsible for creating "`@package`" tags.
+ *
+ * See {@see PackageTag} for details about this tag.
+ */
+final class PackageTagFactory implements TagFactoryInterface
+{
+    private readonly SubPackageTagFactory $factory;
+
+    public function __construct(
+        TypesParserInterface $parser = new TypesParser(tolerant: true),
+    ) {
+        $this->factory = new SubPackageTagFactory($parser);
+    }
+
+    public function create(string $tag, string $content, DescriptionParserInterface $descriptions): PackageTag
+    {
+        $result = $this->factory->create($tag, $content, $descriptions);
+
+        return new PackageTag(
+            name: $result->name,
+            package: $result->package,
+            description: $result->description,
+        );
+    }
+}

src/DocBlock/Tag/PackageTag/SubPackageTag.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Tag\PackageTag;
+
+use TypeLang\Parser\Node\Name;
+use TypeLang\PHPDoc\DocBlock\Tag\Tag;
+
+/**
+ * Used to categorize _Element(s)_ into logical subdivisions.
+ *
+ * The "`@subpackage`" tag can be used as a counterpart or supplement to
+ * Namespaces. Namespaces provide a functional subdivision of _Element(s)_
+ * where the "`@subpackage`" tag can provide a logical subdivision in
+ * which way the elements can be grouped with a different hierarchy.
+ *
+ * If, across the board, both logical and functional subdivisions
+ * are equal, it is NOT RECOMMENDED to use the "`@subpackage`"
+ * tag to prevent maintenance overhead.
+ *
+ * The "`@subpackage`" tag MUST only be used in a select set of
+ * DocBlocks, as is described in the documentation for the "`@package`"
+ * tag. It MUST also accompany a "`@package`" tag and may occur
+ * only once per DocBlock.
+ *
+ * This tag is considered superseded by the support for multiple levels
+ * in the "`@package`" tag and is as such considered deprecated.
+ *
+ * ```
+ * ""`@subpackage`"" <namespace> [<description>]
+ * ```
+ */
+class SubPackageTag extends Tag
+{
+    public function __construct(
+        string $name,
+        public readonly Name $package,
+        \Stringable|string|null $description = null,
+    ) {
+        parent::__construct($name, $description);
+    }
+}

src/DocBlock/Tag/PackageTag/SubPackageTagFactory.php

@@ -0,0 +1,59 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PHPDoc\DocBlock\Tag\PackageTag;
+
+use TypeLang\Parser\Node\Stmt\NamedTypeNode;
+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\TypeReader;
+use TypeLang\PHPDoc\Parser\Description\DescriptionParserInterface;
+
+/**
+ * This class is responsible for creating "`@subpackage`" tags.
+ *
+ * See {@see SubPackageTag} for details about this tag.
+ */
+final class SubPackageTagFactory implements TagFactoryInterface
+{
+    public function __construct(
+        private readonly TypesParserInterface $parser = new TypesParser(tolerant: true),
+    ) {}
+
+    public function create(string $tag, string $content, DescriptionParserInterface $descriptions): SubPackageTag
+    {
+        $stream = new Stream($tag, $content);
+
+        $type = $stream->apply(new TypeReader($this->parser));
+
+        if (!$type instanceof NamedTypeNode) {
+            throw $stream->toException(\sprintf(
+                'Tag @%s expects the namespace to be defined',
+                $stream->tag,
+            ));
+        }
+
+        if ($type->arguments !== null) {
+            throw $stream->toException(\sprintf(
+                'Tag @%s namespace cannot contain template arguments',
+                $stream->tag,
+            ));
+        }
+
+        if ($type->fields !== null) {
+            throw $stream->toException(\sprintf(
+                'Tag @%s namespace cannot contain shape fields',
+                $stream->tag,
+            ));
+        }
+
+        return new SubPackageTag(
+            name: $tag,
+            package: $type->name,
+            description: $stream->toOptionalDescription($descriptions),
+        );
+    }
+}

src/DocBlock/Tag/ParamTag/ParamTag.php

@@ -28,7 +28,7 @@
  * limited to structural elements of type method or function.
  *
  * ```
- * "@param" [<Type>] $<variable> [<description>]
+ * "@param" [<type>] $<variable> [<description>]
  * ```
  */
 class ParamTag extends Tag implements

src/DocBlock/Tag/PropertyTag/PropertyReadTag.php

@@ -6,7 +6,7 @@
 
 /**
  * ```
- * "@property-read" [<Type>] $<name> [<description>]
+ * "@property-read" [<type>] $<name> [<description>]
  * ```
  */
 class PropertyReadTag extends PropertyTag {}

src/DocBlock/Tag/PropertyTag/PropertyTag.php

@@ -34,7 +34,7 @@
  * - Also {@see PropertyWriteTag} for "`@property-write`" tag implementation.
  *
  * ```
- * "@property" [<Type>] $<name> [<description>]
+ * "@property" [<type>] $<name> [<description>]
  * ```
  */
 class PropertyTag extends Tag implements

src/DocBlock/Tag/PropertyTag/PropertyWriteTag.php

@@ -6,7 +6,7 @@
 
 /**
  * ```
- * "@property-write" [<Type>] $<name> [<description>]
+ * "@property-write" [<type>] $<name> [<description>]
  * ```
  */
 class PropertyWriteTag extends PropertyTag {}

src/DocBlock/Tag/ReturnTag/ReturnTag.php

@@ -30,7 +30,7 @@
  * structural elements of type method or function.
  *
  * ```
- * "@return" [<Type>] [<description>]
+ * "@return" [<type>] [<description>]
  * ```
  */
 class ReturnTag extends Tag implements TypeProviderInterface

src/DocBlock/Tag/TemplateExtendsTag/TemplateExtendsTag.php

@@ -6,7 +6,7 @@
 
 /**
  * ```
- * "@extends" <Type> [<description>]
+ * "@extends" <type> [<description>]
  * ```
  */
 class TemplateExtendsTag extends TemplateInheritanceTag {}

src/DocBlock/Tag/TemplateExtendsTag/TemplateImplementsTag.php

@@ -6,7 +6,7 @@
 
 /**
  * ```
- * "@implements" <Type> [<description>]
+ * "@implements" <type> [<description>]
  * ```
  */
 class TemplateImplementsTag extends TemplateInheritanceTag {}

src/DocBlock/Tag/TemplateExtendsTag/TemplateUseTag.php

@@ -6,7 +6,7 @@
 
 /**
  * ```
- * "@use" <Type> [<description>]
+ * "@use" <type> [<description>]
  * ```
  */
 class TemplateUseTag extends TemplateInheritanceTag {}

src/DocBlock/Tag/TemplateTag/TemplateContravariantTag.php

@@ -6,7 +6,7 @@
 
 /**
  * ```
- * "@template-contravariant" <name> ['of' <Type>] [<description>]
+ * "@template-contravariant" <name> ['of' <type>] [<description>]
  * ```
  */
 final class TemplateContravariantTag extends TemplateTag {}

src/DocBlock/Tag/TemplateTag/TemplateCovariantTag.php

@@ -6,7 +6,7 @@
 
 /**
  * ```
- * "@template-covariant" <name> ['of' <Type>] [<description>]
+ * "@template-covariant" <name> ['of' <type>] [<description>]
  * ```
  */
 final class TemplateCovariantTag extends TemplateTag {}

src/DocBlock/Tag/TemplateTag/TemplateTag.php

@@ -10,7 +10,7 @@
 
 /**
  * ```
- * "@template" <name> ['of' <Type>] [<description>]
+ * "@template" <name> ['of' <type>] [<description>]
  * ```
  */
 class TemplateTag extends Tag implements OptionalTypeProviderInterface

src/DocBlock/Tag/ThrowsTag/ThrowsTag.php

@@ -25,7 +25,7 @@
  * detailed view is created and the consumer knows for which errors to check.
  *
  * ```
- * "@throws" [<Type>] [<description>]
+ * "@throws" [<type>] [<description>]
  * ```
  */
 class ThrowsTag extends Tag implements TypeProviderInterface

src/DocBlock/Tag/VarTag/VarTag.php

@@ -26,11 +26,11 @@
  * while several items are represented.
  *
  * ```
- * "@var" [<Type>] $<variable>      [<description>]
- * "@var" [<Type>] ...$<variable>   [<description>]
- * "@var" [<Type>] &$<variable>     [<description>]
- * "@var" [<Type>] ...&$<variable>  [<description>]
- * "@var" [<Type>] &...$<variable>  [<description>]
+ * "@var" [<type>] $<variable>      [<description>]
+ * "@var" [<type>] ...$<variable>   [<description>]
+ * "@var" [<type>] &$<variable>     [<description>]
+ * "@var" [<type>] ...&$<variable>  [<description>]
+ * "@var" [<type>] &...$<variable>  [<description>]
  * ```
  */
 class VarTag extends Tag implements

src/Platform/StandardPlatform.php

@@ -18,6 +18,8 @@
 use TypeLang\PHPDoc\DocBlock\Tag\MethodTag\MethodTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\NoNamedArgumentsTag\NoNamedArgumentsTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\OverrideTag\OverrideTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\PackageTag\PackageTagFactory;
+use TypeLang\PHPDoc\DocBlock\Tag\PackageTag\SubPackageTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\ParamTag\ParamTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\PropertyTag\PropertyReadTagFactory;
 use TypeLang\PHPDoc\DocBlock\Tag\PropertyTag\PropertyTagFactory;
@@ -54,13 +56,15 @@ protected function load(TypesParserInterface $types): iterable
         yield 'link' => new LinkTagFactory();
         yield 'method' => new MethodTagFactory($types);
         yield 'no-named-arguments' => new NoNamedArgumentsTagFactory();
+        yield 'package' => new PackageTagFactory($types);
         yield 'override' => new OverrideTagFactory();
         yield 'param' => new ParamTagFactory($types);
         yield 'property' => new PropertyTagFactory($types);
         yield 'property-read' => new PropertyReadTagFactory($types);
         yield 'property-write' => new PropertyWriteTagFactory($types);
         yield 'return' => new ReturnTagFactory($types);
         yield 'see' => new SeeTagFactory($types);
+        yield 'subpackage' => new SubPackageTagFactory($types);
         yield 'template' => new TemplateTagFactory($types);
         yield 'template-contravariant' => new TemplateContravariantTagFactory($types);
         yield 'template-covariant' => new TemplateCovariantTagFactory($types);