Add more named tags

Author: SerafimArts

docs/Writerside/tl.tree

@@ -186,11 +186,11 @@
             <toc-element topic="psalm-self-out-tag.md" />
             <toc-element topic="psalm-stub-override-tag.md" />
             <toc-element topic="psalm-suppress-tag.md" />
-            <toc-element topic="psalm-taint-escape-tag.md" wip="true" />
+            <toc-element topic="psalm-taint-escape-tag.md" />
             <toc-element topic="psalm-taint-sink-tag.md" wip="true" />
-            <toc-element topic="psalm-taint-source-tag.md" wip="true" />
+            <toc-element topic="psalm-taint-source-tag.md" />
             <toc-element topic="psalm-taint-specialize-tag.md" />
-            <toc-element topic="psalm-taint-unescape-tag.md" wip="true" />
+            <toc-element topic="psalm-taint-unescape-tag.md" />
             <toc-element topic="psalm-template-tag.md" />
             <toc-element topic="psalm-template-contravariant-tag.md" />
             <toc-element topic="psalm-template-covariant-tag.md" />
@@ -285,19 +285,19 @@
             <toc-element topic="phanclosurescope-tag.md" />
         </toc-element>
         <toc-element toc-title="PhpStorm" topic="phpstorm-tags.md">
-            <toc-element topic="noinspection-tag.md" wip="true" />
-            <toc-element topic="language-tag.md" wip="true" />
+            <toc-element topic="noinspection-tag.md" />
+            <toc-element topic="language-tag.md" />
             <toc-element topic="expected-exception-tag.md" />
             <toc-element topic="formatter-off-tag.md" />
             <toc-element topic="formatter-on-tag.md" />
         </toc-element>
         <toc-element toc-title="PHP CodeSniffer" topic="phpcs-tags.md">
-            <toc-element topic="phpcs-suppress-tag.md" wip="true" />
+            <toc-element topic="phpcs-suppress-tag.md" />
             <toc-element topic="coding-standards-ignore-start-tag.md" />
             <toc-element topic="coding-standards-ignore-end-tag.md" />
             <toc-element topic="coding-standards-ignore-line-tag.md" />
             <toc-element topic="coding-standards-ignore-file-tag.md" />
-            <toc-element topic="coding-standards-tag.md" wip="true" />
+            <toc-element topic="coding-standards-tag.md" />
         </toc-element>
         <toc-element topic="custom-tags.md" toc-title="Custom Tags">
             <toc-element topic="tags.md" />

docs/Writerside/topics/phpdoc/tags/coding-standards-tag.md

@@ -1,7 +1,6 @@
 # @codingStandards
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@codingStandards` tag names a coding standard for reference. This is
 pre-3.2.0 PHP_CodeSniffer-era syntax; current PHP_CodeSniffer prefers the
@@ -11,12 +10,12 @@ pre-3.2.0 PHP_CodeSniffer-era syntax; current PHP_CodeSniffer prefers the
 "@codingStandards" <Name> [ <Description> ]
 ```
 
-<note>
-Not yet recognized by <code>TypeLang\PhpDoc\DocBlockParser</code> — parsing
-a docblock containing this tag returns a plain <code>Tag</code>, its whole
-suffix folded into the description. See
-<a href="custom-tags.md">Custom Tags</a> for the current workaround if you
-need to recognize it yourself.
-</note>
+Parsing a `@codingStandards` tag produces a `CodingStandardsTag` instance, carrying the
+parsed `$identifier` alongside the `$name` and optional `$description`
+every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class CodingStandardsTag extends IdentifierTag {}
+```
 
 Associated with PHP_CodeSniffer.

docs/Writerside/topics/phpdoc/tags/language-tag.md

@@ -1,23 +1,22 @@
 # @language
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@language` tag injects a foreign-language grammar — SQL, HTML,
 regular expressions, and the like — into a string literal, so PhpStorm can
 apply the right syntax highlighting and completion inside it.
 
 ```
-"@language" <Name>
+"@language" <Name> [ <Description> ]
 ```
 
-<note>
-Not yet recognized by <code>TypeLang\PhpDoc\DocBlockParser</code> — parsing
-a docblock containing this tag returns a plain <code>Tag</code>, its whole
-suffix folded into the description. See
-<a href="custom-tags.md">Custom Tags</a> for the current workaround if you
-need to recognize it yourself.
-</note>
+Parsing a `@language` tag produces a `LanguageTag` instance, carrying the
+parsed `$identifier` alongside the `$name` and optional `$description`
+every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class LanguageTag extends IdentifierTag {}
+```
 
 Associated with PhpStorm; no dedicated JetBrains page documenting this
 exact doc-comment tag could be confirmed.

docs/Writerside/topics/phpdoc/tags/noinspection-tag.md

@@ -1,7 +1,6 @@
 # @noinspection
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@noinspection` tag suppresses one or more named IDE inspections for
 the element that follows it, so PhpStorm stops flagging a specific,
@@ -11,12 +10,12 @@ intentional pattern in that spot.
 "@noinspection" <Name> [ <Description> ]
 ```
 
-<note>
-Not yet recognized by <code>TypeLang\PhpDoc\DocBlockParser</code> — parsing
-a docblock containing this tag returns a plain <code>Tag</code>, its whole
-suffix folded into the description. See
-<a href="custom-tags.md">Custom Tags</a> for the current workaround if you
-need to recognize it yourself.
-</note>
+Parsing a `@noinspection` tag produces a `NoinspectionTag` instance, carrying the
+parsed `$identifier` alongside the `$name` and optional `$description`
+every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class NoinspectionTag extends IdentifierTag {}
+```
 
 Defined by [PhpStorm](https://www.jetbrains.com/help/phpstorm/disabling-and-enabling-inspections.html).

docs/Writerside/topics/phpdoc/tags/phpcs-suppress-tag.md

@@ -1,7 +1,6 @@
 # @phpcsSuppress
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phpcsSuppress` tag is pre-3.2.0 PHP_CodeSniffer syntax for
 suppressing named coding-standard checks; current PHP_CodeSniffer prefers
@@ -12,12 +11,12 @@ tag-based forms.
 "@phpcsSuppress" <Name> [ <Description> ]
 ```
 
-<note>
-Not yet recognized by <code>TypeLang\PhpDoc\DocBlockParser</code> — parsing
-a docblock containing this tag returns a plain <code>Tag</code>, its whole
-suffix folded into the description. See
-<a href="custom-tags.md">Custom Tags</a> for the current workaround if you
-need to recognize it yourself.
-</note>
+Parsing a `@phpcsSuppress` tag produces a `PhpcsSuppressTag` instance, carrying the
+parsed `$identifier` alongside the `$name` and optional `$description`
+every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class PhpcsSuppressTag extends IdentifierTag {}
+```
 
 Associated with PHP_CodeSniffer.

docs/Writerside/topics/phpdoc/tags/psalm-taint-escape-tag.md

@@ -1,22 +1,21 @@
 # @psalm-taint-escape
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@psalm-taint-escape` tag marks a value as no longer tainted
 after passing through the described element. It is part of Psalm's
 taint-analysis annotations.
 
 ```
-"@psalm-taint-escape" <Name>
+"@psalm-taint-escape" <Name> [ <Description> ]
 ```
 
-<note>
-Not yet recognized by <code>TypeLang\PhpDoc\DocBlockParser</code> — parsing
-a docblock containing this tag returns a plain <code>Tag</code>, its whole
-suffix folded into the description. See
-<a href="custom-tags.md">Custom Tags</a> for the current workaround if you
-need to recognize it yourself.
-</note>
+Parsing a `@psalm-taint-escape` tag produces a `PsalmTaintEscapeTag` instance, carrying the
+parsed `$identifier` alongside the `$name` and optional `$description`
+every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class PsalmTaintEscapeTag extends IdentifierTag {}
+```
 
 See [Psalm's security analysis annotations](https://psalm.dev/docs/security_analysis/annotations/).

docs/Writerside/topics/phpdoc/tags/psalm-taint-source-tag.md

@@ -1,22 +1,21 @@
 # @psalm-taint-source
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@psalm-taint-source` tag marks the return value as a taint
 source of the given type. It is part of Psalm's taint-analysis
 annotations.
 
 ```
-"@psalm-taint-source" <Name>
+"@psalm-taint-source" <Name> [ <Description> ]
 ```
 
-<note>
-Not yet recognized by <code>TypeLang\PhpDoc\DocBlockParser</code> — parsing
-a docblock containing this tag returns a plain <code>Tag</code>, its whole
-suffix folded into the description. See
-<a href="custom-tags.md">Custom Tags</a> for the current workaround if you
-need to recognize it yourself.
-</note>
+Parsing a `@psalm-taint-source` tag produces a `PsalmTaintSourceTag` instance, carrying the
+parsed `$identifier` alongside the `$name` and optional `$description`
+every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class PsalmTaintSourceTag extends IdentifierTag {}
+```
 
 See [Psalm's security analysis annotations](https://psalm.dev/docs/security_analysis/annotations/#psalm-taint-source-lttaint-typegt).

docs/Writerside/topics/phpdoc/tags/psalm-taint-unescape-tag.md

@@ -1,23 +1,22 @@
 # @psalm-taint-unescape
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@psalm-taint-unescape` tag marks a value as tainted again after
 passing through the described element, reversing an earlier
 [@psalm-taint-escape](psalm-taint-escape-tag.md). It is part of
 Psalm's taint-analysis annotations.
 
 ```
-"@psalm-taint-unescape" <Name>
+"@psalm-taint-unescape" <Name> [ <Description> ]
 ```
 
-<note>
-Not yet recognized by <code>TypeLang\PhpDoc\DocBlockParser</code> — parsing
-a docblock containing this tag returns a plain <code>Tag</code>, its whole
-suffix folded into the description. See
-<a href="custom-tags.md">Custom Tags</a> for the current workaround if you
-need to recognize it yourself.
-</note>
+Parsing a `@psalm-taint-unescape` tag produces a `PsalmTaintUnescapeTag` instance, carrying the
+parsed `$identifier` alongside the `$name` and optional `$description`
+every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class PsalmTaintUnescapeTag extends IdentifierTag {}
+```
 
 See [Psalm's security analysis annotations](https://psalm.dev/docs/security_analysis/annotations/).

libs/phpdoc/src/DocBlock/Tag/CodingStandardsTag/CodingStandardsTag.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDoc\DocBlock\Tag\CodingStandardsTag;
+
+use TypeLang\PhpDoc\DocBlock\Tag\IdentifierTag;
+
+/**
+ * The "@codingStandards" tag names a coding standard for reference.
+ */
+final class CodingStandardsTag extends IdentifierTag {}

libs/phpdoc/src/DocBlock/Tag/CodingStandardsTag/CodingStandardsTagDefinition.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TypeLang\PhpDoc\DocBlock\Tag\CodingStandardsTag;
+
+use TypeLang\PhpDoc\DocBlock\Combinator\DescriptionCombinator;
+use TypeLang\PhpDoc\DocBlock\Combinator\NameCombinator;
+use TypeLang\PhpDoc\DocBlock\Description\DescriptionInterface;
+use TypeLang\PhpDoc\DocBlock\TagDefinition\Spec;
+use TypeLang\PhpDoc\DocBlock\TagDefinition\TagDefinition;
+use TypeLang\PhpDoc\DocBlock\TagDefinition\TagPayload;
+use TypeLang\PhpDoc\DocBlock\TagDefinition\TagPlacement;
+
+/**
+ * The "`@codingStandards`" tag names a coding standard for reference.
+ *
+ * ```
+ * "@codingStandards" <Name> [ <Description> ]
+ * ```
+ */
+final class CodingStandardsTagDefinition extends TagDefinition
+{
+    public const string NAME = 'codingStandards';
+
+    public function __construct()
+    {
+        parent::__construct(
+            name: self::NAME,
+            spec: Spec::sequence(
+                Spec::rule(NameCombinator::NAME, 'identifier'),
+                Spec::maybe(
+                    Spec::rule(DescriptionCombinator::NAME, 'description'),
+                ),
+            ),
+            placement: TagPlacement::Block,
+        );
+    }
+
+    public function create(string $name, TagPayload $result): CodingStandardsTag
+    {
+        /** @var non-empty-string $identifier */
+        $identifier = $result->get('identifier');
+
+        /** @var DescriptionInterface|null $description */
+        $description = $result->find('description');
+
+        return new CodingStandardsTag($name, $identifier, $description);
+    }
+}