Add typed tags

Author: SerafimArts

docs/Writerside/tl.tree

@@ -152,7 +152,7 @@
             <toc-element topic="psalm-external-mutation-free-tag.md" />
             <toc-element topic="psalm-extends-tag.md" />
             <toc-element topic="psalm-flow-tag.md" wip="true" />
-            <toc-element topic="psalm-if-this-is-tag.md" wip="true" />
+            <toc-element topic="psalm-if-this-is-tag.md" />
             <toc-element topic="psalm-ignore-falsable-return-tag.md" />
             <toc-element topic="psalm-ignore-nullable-return-tag.md" />
             <toc-element topic="psalm-ignore-var-tag.md" />
@@ -161,7 +161,7 @@
             <toc-element topic="psalm-immutable-tag.md" />
             <toc-element topic="psalm-implements-tag.md" />
             <toc-element topic="psalm-import-type-tag.md" wip="true" />
-            <toc-element topic="psalm-inheritors-tag.md" wip="true" />
+            <toc-element topic="psalm-inheritors-tag.md" />
             <toc-element topic="psalm-internal-tag.md" />
             <toc-element topic="psalm-method-tag.md" />
             <toc-element topic="psalm-mutation-free-tag.md" />
@@ -180,10 +180,10 @@
             <toc-element topic="psalm-require-extends-tag.md" />
             <toc-element topic="psalm-require-implements-tag.md" />
             <toc-element topic="psalm-return-tag.md" />
-            <toc-element topic="psalm-scope-this-tag.md" wip="true" />
+            <toc-element topic="psalm-scope-this-tag.md" />
             <toc-element topic="psalm-seal-methods-tag.md" />
             <toc-element topic="psalm-seal-properties-tag.md" />
-            <toc-element topic="psalm-self-out-tag.md" wip="true" />
+            <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" />
@@ -194,13 +194,13 @@
             <toc-element topic="psalm-template-tag.md" />
             <toc-element topic="psalm-template-contravariant-tag.md" />
             <toc-element topic="psalm-template-covariant-tag.md" />
-            <toc-element topic="psalm-this-out-tag.md" wip="true" />
+            <toc-element topic="psalm-this-out-tag.md" />
             <toc-element topic="psalm-trace-tag.md" />
             <toc-element topic="psalm-type-tag.md" wip="true" />
             <toc-element topic="psalm-use-tag.md" />
             <toc-element topic="psalm-var-tag.md" />
             <toc-element topic="psalm-variadic-tag.md" />
-            <toc-element topic="psalm-yield-tag.md" wip="true" />
+            <toc-element topic="psalm-yield-tag.md" />
         </toc-element>
         <toc-element toc-title="PHPStan" topic="phpstan-tags.md">
             <toc-element topic="phpstan-allow-private-mutation-tag.md" />
@@ -232,16 +232,16 @@
             <toc-element topic="phpstan-require-extends-tag.md" />
             <toc-element topic="phpstan-require-implements-tag.md" />
             <toc-element topic="phpstan-return-tag.md" />
-            <toc-element topic="phpstan-self-out-tag.md" wip="true" />
+            <toc-element topic="phpstan-self-out-tag.md" />
             <toc-element topic="phpstan-template-tag.md" />
             <toc-element topic="phpstan-template-contravariant-tag.md" />
             <toc-element topic="phpstan-template-covariant-tag.md" />
-            <toc-element topic="phpstan-this-out-tag.md" wip="true" />
+            <toc-element topic="phpstan-this-out-tag.md" />
             <toc-element topic="phpstan-throws-tag.md" />
             <toc-element topic="phpstan-type-tag.md" wip="true" />
             <toc-element topic="phpstan-use-tag.md" />
             <toc-element topic="phpstan-var-tag.md" />
-            <toc-element topic="phpstan-yield-tag.md" wip="true" />
+            <toc-element topic="phpstan-yield-tag.md" />
         </toc-element>
         <toc-element toc-title="Phan" topic="phan-tags.md">
             <toc-element topic="phan-abstract-tag.md" />
@@ -250,13 +250,13 @@
             <toc-element topic="phan-assert-if-false-tag.md" wip="true" />
             <toc-element topic="phan-assert-if-true-tag.md" wip="true" />
             <toc-element topic="phan-assert-true-condition-tag.md" wip="true" />
-            <toc-element topic="phan-closure-scope-tag.md" wip="true" />
+            <toc-element topic="phan-closure-scope-tag.md" />
             <toc-element topic="phan-constructor-used-for-side-effects-tag.md" />
             <toc-element topic="phan-extends-tag.md" />
             <toc-element topic="phan-file-suppress-tag.md" wip="true" />
             <toc-element topic="phan-forbid-undeclared-magic-methods-tag.md" />
             <toc-element topic="phan-forbid-undeclared-magic-properties-tag.md" />
-            <toc-element topic="phan-hardcode-return-type-tag.md" wip="true" />
+            <toc-element topic="phan-hardcode-return-type-tag.md" />
             <toc-element topic="phan-immutable-tag.md" />
             <toc-element topic="phan-inherits-tag.md" />
             <toc-element topic="phan-method-tag.md" />
@@ -269,7 +269,7 @@
             <toc-element topic="phan-property-write-tag.md" />
             <toc-element topic="phan-pure-tag.md" />
             <toc-element topic="phan-read-only-tag.md" />
-            <toc-element topic="phan-real-return-tag.md" wip="true" />
+            <toc-element topic="phan-real-return-tag.md" />
             <toc-element topic="phan-return-tag.md" />
             <toc-element topic="phan-side-effect-free-tag.md" />
             <toc-element topic="phan-suppress-current-line-tag.md" wip="true" />
@@ -282,12 +282,12 @@
             <toc-element topic="phan-unused-param-tag.md" />
             <toc-element topic="phan-var-tag.md" />
             <toc-element topic="phan-write-only-tag.md" />
-            <toc-element topic="phanclosurescope-tag.md" wip="true" />
+            <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="expected-exception-tag.md" wip="true" />
+            <toc-element topic="expected-exception-tag.md" />
             <toc-element topic="formatter-off-tag.md" />
             <toc-element topic="formatter-on-tag.md" />
         </toc-element>

docs/Writerside/topics/phpdoc/tags/expected-exception-tag.md

@@ -1,7 +1,6 @@
 # @expectedException
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@expectedException` tag declares the `Throwable` a test method is
 expected to throw. It is an old PHPUnit-era convention that predates the
@@ -11,12 +10,12 @@ expected to throw. It is an old PHPUnit-era convention that predates the
 "@expectedException" <Type> [ <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 `@expectedException` tag produces a `ExpectedExceptionTag` instance, carrying the
+parsed `$type` alongside the `$name` and optional `$description` every
+[Tag](phpdoc.md#tag) already provides.
+
+```php
+final class ExpectedExceptionTag extends TypedTag {}
+```
 
 A historical PHPUnit convention, not a PhpStorm tag.

docs/Writerside/topics/phpdoc/tags/phan-closure-scope-tag.md

@@ -1,7 +1,6 @@
 # @phan-closure-scope
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phan-closure-scope` tag binds the type of `$this` inside a
 `Closure`, letting Phan analyze the closure's body as though it were
@@ -11,12 +10,12 @@ bound to an instance of the given class.
 "@phan-closure-scope" <Type>
 ```
 
-<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 `@phan-closure-scope` tag produces a `PhanClosureScopeTag` instance, carrying the
+parsed `$type` alongside the `$name` and optional `$description` every
+[Tag](phpdoc.md#tag) already provides.
+
+```php
+final class PhanClosureScopeTag extends TypedTag {}
+```
 
 Defined by [Phan's Annotating Your Source Code wiki](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code#phan-closure-scope).

docs/Writerside/topics/phpdoc/tags/phan-hardcode-return-type-tag.md

@@ -1,18 +1,21 @@
 # @phan-hardcode-return-type
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phan-hardcode-return-type` tag forces Phan to use the
 documented return type instead of the type it would otherwise infer
 from the method body.
 
-<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>
+```
+"@phan-hardcode-return-type" <Type> [ <Description> ]
+```
+
+Parsing a `@phan-hardcode-return-type` tag produces a `PhanHardcodeReturnTypeTag` instance, carrying the
+parsed `$type` alongside the `$name` and optional `$description` every
+[Tag](phpdoc.md#tag) already provides.
+
+```php
+final class PhanHardcodeReturnTypeTag extends TypedTag {}
+```
 
 Defined by Phan.

docs/Writerside/topics/phpdoc/tags/phan-real-return-tag.md

@@ -1,19 +1,22 @@
 # @phan-real-return
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phan-real-return` tag documents the actual native return
 type of a function or method, kept distinct from the type
 documented via [@return](return-tag.md).
 
-<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>
+```
+"@phan-real-return" <Type> [ <Description> ]
+```
+
+Parsing a `@phan-real-return` tag produces a `PhanRealReturnTag` instance, carrying the
+parsed `$type` alongside the `$name` and optional `$description` every
+[Tag](phpdoc.md#tag) already provides.
+
+```php
+final class PhanRealReturnTag extends TypedTag {}
+```
 
 Defined by Phan, a static analyzer for PHP; no dedicated
 documentation page could be confirmed for this tag.

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

@@ -1,18 +1,15 @@
 # @phanclosurescope
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
+<secondary-label ref="alias-tag"/>
 
 The `@phanclosurescope` tag is an older alias of
 [@phan-closure-scope](phan-closure-scope-tag.md), binding the
 type of `$this` inside a `Closure`.
 
-<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>
+This library recognizes `@phanclosurescope` as an alias of the canonical
+[@phan-closure-scope](phan-closure-scope-tag.md) tag: it parses identically and produces
+the exact same tag instance, keeping the vendor-prefixed name it was
+written with.
 
 Defined by [Phan](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code).

docs/Writerside/topics/phpdoc/tags/phpstan-self-out-tag.md

@@ -1,21 +1,26 @@
 # @phpstan-self-out
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phpstan-self-out` tag documents the refined type of `$this`
 after a method call, letting PHPStan track how a fluent or
 mutating method narrows the object's own type. It is defined by the
 static analyzer PHPStan, which also accepts the alias
 `@phpstan-this-out` (see [phpstan-this-out-tag.md](phpstan-this-out-tag.md)).
 
-<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>
+```
+"@phpstan-self-out" <Type> [ <Description> ]
+```
+
+Parsing a `@phpstan-self-out` tag produces a `SelfOutTag` instance, carrying the
+parsed `$type` alongside the `$name` and optional `$description` every
+[Tag](phpdoc.md#tag) already provides.
+
+```php
+final class SelfOutTag extends TypedTag {}
+```
+
+The same `SelfOutTag` is produced by [@psalm-self-out](psalm-self-out-tag.md), which restates the same concept for its tool.
 
 See PHPStan's
 [PHPDoc basics](https://phpstan.org/writing-php-code/phpdocs-basics#change-type-of-current-object-after-calling-a-method).

docs/Writerside/topics/phpdoc/tags/phpstan-this-out-tag.md

@@ -1,19 +1,16 @@
 # @phpstan-this-out
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
+<secondary-label ref="alias-tag"/>
 
 The `@phpstan-this-out` tag is an alias of `@phpstan-self-out` (see
 [phpstan-self-out-tag.md](phpstan-self-out-tag.md)). It documents
 the refined type of `$this` after a method call.
 
-<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>
+This library recognizes `@phpstan-this-out` as an alias of the canonical
+[@phpstan-self-out](phpstan-self-out-tag.md) tag: it parses identically and produces
+the exact same tag instance, keeping the vendor-prefixed name it was
+written with.
 
 See PHPStan's
 [PHPDoc basics](https://phpstan.org/writing-php-code/phpdocs-basics#change-type-of-current-object-after-calling-a-method).

docs/Writerside/topics/phpdoc/tags/phpstan-yield-tag.md

@@ -1,7 +1,6 @@
 # @phpstan-yield
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phpstan-yield` tag documents the type yielded by a
 `Generator`, distinct from the type it returns on completion. It is
@@ -11,12 +10,14 @@ defined by the static analyzer PHPStan.
 "@phpstan-yield" <Type> [ <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 `@phpstan-yield` tag produces a `YieldTag` instance, carrying the
+parsed `$type` alongside the `$name` and optional `$description` every
+[Tag](phpdoc.md#tag) already provides.
+
+```php
+final class YieldTag extends TypedTag {}
+```
+
+The same `YieldTag` is produced by [@psalm-yield](psalm-yield-tag.md), which restates the same concept for its tool.
 
 See PHPStan's [PHPDoc basics](https://phpstan.org/writing-php-code/phpdocs-basics) page.

docs/Writerside/topics/phpdoc/tags/psalm-if-this-is-tag.md

@@ -1,7 +1,6 @@
 # @psalm-if-this-is
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@psalm-if-this-is` tag narrows the type of `$this` inside a
 method when the given type matches. It is defined by the static
@@ -11,12 +10,12 @@ analyzer Psalm, alongside [@psalm-assert](psalm-assert-tag.md).
 "@psalm-if-this-is" <Type>
 ```
 
-<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-if-this-is` tag produces a `PsalmIfThisIsTag` instance, carrying the
+parsed `$type` alongside the `$name` and optional `$description` every
+[Tag](phpdoc.md#tag) already provides.
+
+```php
+final class PsalmIfThisIsTag extends TypedTag {}
+```
 
 See [Psalm's supported annotations](https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-assert-psalm-assert-if-true-psalm-assert-if-false-psalm-if-this-is-and-psalm-this-out).