Add psalm flow tag

Author: SerafimArts

Writerside/tl.tree

@@ -145,13 +145,13 @@
             <toc-element topic="psalm-assert-if-false-tag.md" />
             <toc-element topic="psalm-assert-if-true-tag.md" />
             <toc-element topic="psalm-assert-untainted-tag.md" />
-            <toc-element topic="psalm-check-type-tag.md" wip="true" />
-            <toc-element topic="psalm-check-type-exact-tag.md" wip="true" />
+            <toc-element topic="psalm-check-type-tag.md" />
+            <toc-element topic="psalm-check-type-exact-tag.md" />
             <toc-element topic="psalm-consistent-constructor-tag.md" />
             <toc-element topic="psalm-consistent-templates-tag.md" />
             <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-flow-tag.md" />
             <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" />
@@ -160,7 +160,7 @@
             <toc-element topic="psalm-ignore-variable-property-tag.md" />
             <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-import-type-tag.md" />
             <toc-element topic="psalm-inheritors-tag.md" />
             <toc-element topic="psalm-internal-tag.md" />
             <toc-element topic="psalm-method-tag.md" />
@@ -187,7 +187,7 @@
             <toc-element topic="psalm-stub-override-tag.md" />
             <toc-element topic="psalm-suppress-tag.md" />
             <toc-element topic="psalm-taint-escape-tag.md" />
-            <toc-element topic="psalm-taint-sink-tag.md" wip="true" />
+            <toc-element topic="psalm-taint-sink-tag.md" />
             <toc-element topic="psalm-taint-source-tag.md" />
             <toc-element topic="psalm-taint-specialize-tag.md" />
             <toc-element topic="psalm-taint-unescape-tag.md" />
@@ -196,7 +196,7 @@
             <toc-element topic="psalm-template-covariant-tag.md" />
             <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-type-tag.md" />
             <toc-element topic="psalm-use-tag.md" />
             <toc-element topic="psalm-var-tag.md" />
             <toc-element topic="psalm-variadic-tag.md" />
@@ -214,7 +214,7 @@
             <toc-element topic="phpstan-ignore-next-line-tag.md" />
             <toc-element topic="phpstan-immutable-tag.md" />
             <toc-element topic="phpstan-implements-tag.md" />
-            <toc-element topic="phpstan-import-type-tag.md" wip="true" />
+            <toc-element topic="phpstan-import-type-tag.md" />
             <toc-element topic="phpstan-impure-tag.md" />
             <toc-element topic="phpstan-method-tag.md" />
             <toc-element topic="phpstan-param-tag.md" />
@@ -238,7 +238,7 @@
             <toc-element topic="phpstan-template-covariant-tag.md" />
             <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-type-tag.md" />
             <toc-element topic="phpstan-use-tag.md" />
             <toc-element topic="phpstan-var-tag.md" />
             <toc-element topic="phpstan-yield-tag.md" />
@@ -278,7 +278,7 @@
             <toc-element topic="phan-suppress-previous-line-tag.md" />
             <toc-element topic="phan-template-tag.md" />
             <toc-element topic="phan-transient-tag.md" />
-            <toc-element topic="phan-type-tag.md" wip="true" />
+            <toc-element topic="phan-type-tag.md" />
             <toc-element topic="phan-unused-param-tag.md" />
             <toc-element topic="phan-var-tag.md" />
             <toc-element topic="phan-write-only-tag.md" />

Writerside/topics/phpdoc/tags/phan-type-tag.md

@@ -1,21 +1,23 @@
 # @phan-type
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phan-type` tag declares a local alias for a complex type.
 
 ```
-"@phan-type" <Name> "=" <Type>
+"@phan-type" <Name> [ "=" ] <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-type` tag produces a `TypeAliasTag` instance, carrying the
+parsed `$alias` name and its `$type` alongside the `$name` every
+[Tag](phpdoc.md#tag) already provides.
+
+```php
+final class TypeAliasTag extends Tag {}
+```
+
+The same `TypeAliasTag` is produced by [@psalm-type](psalm-type-tag.md) and [@phpstan-type](phpstan-type-tag.md), which restate
+the same concept for their respective tools.
 
 Defined by Phan, a static analyzer for PHP; no dedicated
 documentation page could be confirmed for this tag.

Writerside/topics/phpdoc/tags/phpstan-import-type-tag.md

@@ -1,18 +1,26 @@
 # @phpstan-import-type
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phpstan-import-type` tag imports a `@phpstan-type` alias declared
 in another class, defined by PHPStan.
 
-<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-import-type" <Name> "from" <Type>
+    [ "as" <Name> ]
+```
+
+Parsing a `@phpstan-import-type` tag produces an `ImportTypeAliasTag` instance,
+carrying the imported `$alias`, the `$type` it is imported from, and the
+optional local `$as` name alongside the `$name` every [Tag](phpdoc.md#tag)
+already provides.
+
+```php
+final class ImportTypeAliasTag extends Tag {}
+```
+
+The same `ImportTypeAliasTag` is produced by [@psalm-import-type](psalm-import-type-tag.md), which restates
+the same concept for Psalm.
 
 Documented by
 [PHPStan](https://phpstan.org/writing-php-code/phpdoc-types#local-type-aliases).

Writerside/topics/phpdoc/tags/phpstan-type-tag.md

@@ -1,23 +1,25 @@
 # @phpstan-type
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phpstan-type` tag declares a local alias for a complex type,
 so it can be referenced by name in later `@param`, `@return`, and
 `@var` tags. It is defined by the static analyzer PHPStan.
 
 ```
-"@phpstan-type" <Name> "=" <Type>
+"@phpstan-type" <Name> [ "=" ] <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 `@phpstan-type` tag produces a `TypeAliasTag` instance, carrying the
+parsed `$alias` name and its `$type` alongside the `$name` every
+[Tag](phpdoc.md#tag) already provides.
+
+```php
+final class TypeAliasTag extends Tag {}
+```
+
+The same `TypeAliasTag` is produced by [@psalm-type](psalm-type-tag.md) and [@phan-type](phan-type-tag.md), which restate
+the same concept for their respective tools.
 
 See PHPStan's
 [PHPDoc types](https://phpstan.org/writing-php-code/phpdoc-types#local-type-aliases).

Writerside/topics/phpdoc/tags/psalm-check-type-exact-tag.md

@@ -1,7 +1,6 @@
 # @psalm-check-type-exact
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@psalm-check-type-exact` tag asserts that a variable resolves
 to exactly the given type, disallowing narrower or wider matches.
@@ -12,12 +11,15 @@ It is defined by the static analyzer Psalm, alongside the looser
 "@psalm-check-type-exact" <Variable> "=" <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-check-type-exact` tag produces a `PsalmCheckTypeExactTag`
+instance, carrying the checked `$variable` and its expected `$type` alongside
+the `$name` every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class PsalmCheckTypeExactTag extends CheckTypeTag {}
+```
+
+It shares the `CheckTypeTag` base with the looser
+[@psalm-check-type](psalm-check-type-tag.md), which allows assignable matches.
 
 See [Psalm's supported annotations](https://psalm.dev/docs/annotating_code/supported_annotations/) page.

Writerside/topics/phpdoc/tags/psalm-check-type-tag.md

@@ -1,7 +1,6 @@
 # @psalm-check-type
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@psalm-check-type` tag asserts, for debugging purposes, that a
 variable resolves to a given type. It is defined by the static
@@ -11,12 +10,16 @@ analyzer Psalm.
 "@psalm-check-type" <Variable> "=" <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-check-type` tag produces a `PsalmCheckTypeTag` instance,
+carrying the checked `$variable` and its expected `$type` alongside the
+`$name` every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class PsalmCheckTypeTag extends CheckTypeTag {}
+```
+
+It shares the `CheckTypeTag` base with the stricter
+[@psalm-check-type-exact](psalm-check-type-exact-tag.md), which demands an
+exact type match.
 
 See [Psalm's supported annotations](https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-check-type).

Writerside/topics/phpdoc/tags/psalm-flow-tag.md

@@ -1,7 +1,6 @@
 # @psalm-flow
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@psalm-flow` tag is part of Psalm's taint-analysis annotations,
 used to describe how tainted data flows through a function's
@@ -11,12 +10,15 @@ parameters and return value.
 "@psalm-flow" <FlowType> [ <Variable> ]
 ```
 
-<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>
+The `<FlowType>` is a keyword — one of `TaintSource`, `TaintSink`,
+`TaintSpecialize` or `TaintUnescape` — captured into a `FlowType` enum.
+
+Parsing a `@psalm-flow` tag produces a `PsalmFlowTag` instance, carrying the
+parsed `$flow` and optional `$variable` alongside the `$name` every
+[Tag](phpdoc.md#tag) already provides.
+
+```php
+final class PsalmFlowTag extends Tag {}
+```
 
 See [Psalm's security analysis annotations](https://psalm.dev/docs/security_analysis/annotations/).

Writerside/topics/phpdoc/tags/psalm-import-type-tag.md

@@ -1,7 +1,6 @@
 # @psalm-import-type
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@psalm-import-type` tag imports a `@psalm-type` alias declared in
 another class, optionally binding it to a local alias name.
@@ -11,12 +10,16 @@ another class, optionally binding it to a local alias name.
     [ "as" <Name> ]
 ```
 
-<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-import-type` tag produces an `ImportTypeAliasTag` instance,
+carrying the imported `$alias`, the `$type` it is imported from, and the
+optional local `$as` name alongside the `$name` every [Tag](phpdoc.md#tag)
+already provides.
+
+```php
+final class ImportTypeAliasTag extends Tag {}
+```
+
+The same `ImportTypeAliasTag` is produced by [@phpstan-import-type](phpstan-import-type-tag.md), which restates
+the same concept for PHPStan.
 
 Defined by [Psalm's supported annotations reference](https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-import-type).

Writerside/topics/phpdoc/tags/psalm-taint-sink-tag.md

@@ -1,7 +1,6 @@
 # @psalm-taint-sink
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@psalm-taint-sink` tag marks an argument as a taint sink for
 the given taint type. It is part of Psalm's taint-analysis
@@ -11,12 +10,12 @@ annotations.
 "@psalm-taint-sink" <Name> <Variable>
 ```
 
-<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-sink` tag produces a `PsalmTaintSinkTag` instance,
+carrying the parsed `$taint` type and `$variable` alongside the `$name`
+every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class PsalmTaintSinkTag extends Tag {}
+```
 
 See [Psalm's security analysis annotations](https://psalm.dev/docs/security_analysis/annotations/#psalm-taint-sink-lttaint-typegt-ltparam-namegt).

Writerside/topics/phpdoc/tags/psalm-type-tag.md

@@ -1,22 +1,24 @@
 # @psalm-type
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@psalm-type` tag declares a local alias for a complex type,
 which can then be reused across the codebase. It is defined by the
 static analyzer Psalm.
 
 ```
-"@psalm-type" <Name> "=" <Type>
+"@psalm-type" <Name> [ "=" ] <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-type` tag produces a `TypeAliasTag` instance, carrying the
+parsed `$alias` name and its `$type` alongside the `$name` every
+[Tag](phpdoc.md#tag) already provides.
+
+```php
+final class TypeAliasTag extends Tag {}
+```
+
+The same `TypeAliasTag` is produced by [@phpstan-type](phpstan-type-tag.md) and [@phan-type](phan-type-tag.md), which restate
+the same concept for their respective tools.
 
 See [Psalm's supported annotations](https://psalm.dev/docs/annotating_code/supported_annotations/#psalm-type).