Add *-assert-if-true, *-assert-if-false and *-assert tags

Author: SerafimArts

docs/Writerside/tl.tree

@@ -141,9 +141,9 @@
         <toc-element toc-title="Psalm" topic="psalm-tags.md">
             <toc-element topic="psalm-allow-private-mutation-tag.md" />
             <toc-element topic="psalm-api-tag.md" />
-            <toc-element topic="psalm-assert-tag.md" wip="true" />
-            <toc-element topic="psalm-assert-if-false-tag.md" wip="true" />
-            <toc-element topic="psalm-assert-if-true-tag.md" wip="true" />
+            <toc-element topic="psalm-assert-tag.md" />
+            <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" />
@@ -204,9 +204,9 @@
         </toc-element>
         <toc-element toc-title="PHPStan" topic="phpstan-tags.md">
             <toc-element topic="phpstan-allow-private-mutation-tag.md" />
-            <toc-element topic="phpstan-assert-tag.md" wip="true" />
-            <toc-element topic="phpstan-assert-if-false-tag.md" wip="true" />
-            <toc-element topic="phpstan-assert-if-true-tag.md" wip="true" />
+            <toc-element topic="phpstan-assert-tag.md" />
+            <toc-element topic="phpstan-assert-if-false-tag.md" />
+            <toc-element topic="phpstan-assert-if-true-tag.md" />
             <toc-element topic="phpstan-consistent-constructor-tag.md" />
             <toc-element topic="phpstan-extends-tag.md" />
             <toc-element topic="phpstan-ignore-tag.md" wip="true" />
@@ -245,10 +245,10 @@
         </toc-element>
         <toc-element toc-title="Phan" topic="phan-tags.md">
             <toc-element topic="phan-abstract-tag.md" />
-            <toc-element topic="phan-assert-tag.md" wip="true" />
+            <toc-element topic="phan-assert-tag.md" />
             <toc-element topic="phan-assert-false-condition-tag.md" wip="true" />
-            <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-if-false-tag.md" />
+            <toc-element topic="phan-assert-if-true-tag.md" />
             <toc-element topic="phan-assert-true-condition-tag.md" wip="true" />
             <toc-element topic="phan-closure-scope-tag.md" />
             <toc-element topic="phan-constructor-used-for-side-effects-tag.md" />

docs/Writerside/topics/phpdoc/tags/phan-assert-if-false-tag.md

@@ -1,21 +1,27 @@
 # @phan-assert-if-false
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phan-assert-if-false` tag asserts the given type for an
 argument or variable when the function returns `false`. It belongs
 to the same assertion family as [@phan-assert](phan-assert-tag.md)
 and its counterpart
 [@phan-assert-if-true](phan-assert-if-true-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-assert-if-false" <Type> <Variable> [ <Description> ]
+```
+
+Parsing a `@phan-assert-if-false` tag produces an `AssertIfFalseTag` instance, carrying the
+asserted `$type` and `$variable` alongside the `$name` and optional
+`$description` every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class AssertIfFalseTag extends TypedVariableTag {}
+```
+
+The same `AssertIfFalseTag` is produced by [@psalm-assert-if-false](psalm-assert-if-false-tag.md) and [@phpstan-assert-if-false](phpstan-assert-if-false-tag.md), which restate the same
+assertion for their respective tools.
 
 Defined by Phan; see the "Assertions" section of
 [Phan's Annotating Your Source Code wiki](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code).

docs/Writerside/topics/phpdoc/tags/phan-assert-if-true-tag.md

@@ -1,21 +1,27 @@
 # @phan-assert-if-true
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phan-assert-if-true` tag asserts the given type for an
 argument or variable when the function returns `true`. It belongs
 to the same assertion family as [@phan-assert](phan-assert-tag.md)
 and its counterpart
 [@phan-assert-if-false](phan-assert-if-false-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-assert-if-true" <Type> <Variable> [ <Description> ]
+```
+
+Parsing a `@phan-assert-if-true` tag produces an `AssertIfTrueTag` instance, carrying the
+asserted `$type` and `$variable` alongside the `$name` and optional
+`$description` every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class AssertIfTrueTag extends TypedVariableTag {}
+```
+
+The same `AssertIfTrueTag` is produced by [@psalm-assert-if-true](psalm-assert-if-true-tag.md) and [@phpstan-assert-if-true](phpstan-assert-if-true-tag.md), which restate the same
+assertion for their respective tools.
 
 Defined by Phan; see the "Assertions" section of
 [Phan's Annotating Your Source Code wiki](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code).

docs/Writerside/topics/phpdoc/tags/phan-assert-tag.md

@@ -1,7 +1,6 @@
 # @phan-assert
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phan-assert` tag asserts that an argument or variable is
 narrowed to a given type after the call returns. Phan documents it
@@ -10,13 +9,20 @@ siblings — see [@phan-assert-if-true](phan-assert-if-true-tag.md) and
 [@phan-assert-if-false](phan-assert-if-false-tag.md) — as part of the
 same assertion family.
 
-<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-assert" <Type> <Variable> [ <Description> ]
+```
+
+Parsing a `@phan-assert` tag produces an `AssertTag` instance, carrying the
+asserted `$type` and `$variable` alongside the `$name` and optional
+`$description` every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class AssertTag extends TypedVariableTag {}
+```
+
+The same `AssertTag` is produced by [@psalm-assert](psalm-assert-tag.md) and [@phpstan-assert](phpstan-assert-tag.md), which restate the same
+assertion for their respective tools.
 
 Defined by Phan; see the "Assertions" section of
 [Phan's Annotating Your Source Code wiki](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code).

docs/Writerside/topics/phpdoc/tags/phpstan-assert-if-false-tag.md

@@ -1,19 +1,25 @@
 # @phpstan-assert-if-false
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phpstan-assert-if-false` tag asserts the given type when the
 function returns `false`, defined by PHPStan. It is one of the
 [@phpstan-assert](phpstan-assert-tag.md) family of narrowing tags.
 
-<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-assert-if-false" <Type> <Variable> [ <Description> ]
+```
+
+Parsing a `@phpstan-assert-if-false` tag produces an `AssertIfFalseTag` instance, carrying the
+asserted `$type` and `$variable` alongside the `$name` and optional
+`$description` every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class AssertIfFalseTag extends TypedVariableTag {}
+```
+
+The same `AssertIfFalseTag` is produced by [@psalm-assert-if-false](psalm-assert-if-false-tag.md) and [@phan-assert-if-false](phan-assert-if-false-tag.md), which restate the same
+assertion for their respective tools.
 
 Documented by
 [PHPStan](https://phpstan.org/writing-php-code/phpdocs-basics#narrowing-types-after-function-call).

docs/Writerside/topics/phpdoc/tags/phpstan-assert-if-true-tag.md

@@ -1,19 +1,25 @@
 # @phpstan-assert-if-true
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phpstan-assert-if-true` tag asserts the given type when the
 function returns `true`, defined by PHPStan. It is one of the
 [@phpstan-assert](phpstan-assert-tag.md) family of narrowing tags.
 
-<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-assert-if-true" <Type> <Variable> [ <Description> ]
+```
+
+Parsing a `@phpstan-assert-if-true` tag produces an `AssertIfTrueTag` instance, carrying the
+asserted `$type` and `$variable` alongside the `$name` and optional
+`$description` every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class AssertIfTrueTag extends TypedVariableTag {}
+```
+
+The same `AssertIfTrueTag` is produced by [@psalm-assert-if-true](psalm-assert-if-true-tag.md) and [@phan-assert-if-true](phan-assert-if-true-tag.md), which restate the same
+assertion for their respective tools.
 
 Documented by
 [PHPStan](https://phpstan.org/writing-php-code/phpdocs-basics#narrowing-types-after-function-call).

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

@@ -1,20 +1,26 @@
 # @phpstan-assert
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@phpstan-assert` tag asserts that an argument or variable is
 narrowed to a given type after the call, defined by PHPStan. It has
 `-if-true` and `-if-false` siblings for assertions that only hold when a
 boolean-returning function returns a particular value.
 
-<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-assert" <Type> <Variable> [ <Description> ]
+```
+
+Parsing a `@phpstan-assert` tag produces an `AssertTag` instance, carrying the
+asserted `$type` and `$variable` alongside the `$name` and optional
+`$description` every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class AssertTag extends TypedVariableTag {}
+```
+
+The same `AssertTag` is produced by [@psalm-assert](psalm-assert-tag.md) and [@phan-assert](phan-assert-tag.md), which restate the same
+assertion for their respective tools.
 
 Documented by
 [PHPStan](https://phpstan.org/writing-php-code/phpdocs-basics#narrowing-types-after-function-call).

docs/Writerside/topics/phpdoc/tags/psalm-assert-if-false-tag.md

@@ -1,19 +1,25 @@
 # @psalm-assert-if-false
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@psalm-assert-if-false` tag asserts the given type for an
 argument or variable when the function returns `false`. It is
 defined by the static analyzer Psalm, alongside
 [@psalm-assert](psalm-assert-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>
+```
+"@psalm-assert-if-false" <Type> <Variable> [ <Description> ]
+```
+
+Parsing a `@psalm-assert-if-false` tag produces an `AssertIfFalseTag` instance, carrying the
+asserted `$type` and `$variable` alongside the `$name` and optional
+`$description` every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class AssertIfFalseTag extends TypedVariableTag {}
+```
+
+The same `AssertIfFalseTag` is produced by [@phpstan-assert-if-false](phpstan-assert-if-false-tag.md) and [@phan-assert-if-false](phan-assert-if-false-tag.md), which restate the same
+assertion for their respective tools.
 
 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).

docs/Writerside/topics/phpdoc/tags/psalm-assert-if-true-tag.md

@@ -1,19 +1,25 @@
 # @psalm-assert-if-true
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@psalm-assert-if-true` tag asserts the given type for an
 argument or variable when the function returns `true`. It is
 defined by the static analyzer Psalm, alongside
 [@psalm-assert](psalm-assert-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>
+```
+"@psalm-assert-if-true" <Type> <Variable> [ <Description> ]
+```
+
+Parsing a `@psalm-assert-if-true` tag produces an `AssertIfTrueTag` instance, carrying the
+asserted `$type` and `$variable` alongside the `$name` and optional
+`$description` every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class AssertIfTrueTag extends TypedVariableTag {}
+```
+
+The same `AssertIfTrueTag` is produced by [@phpstan-assert-if-true](phpstan-assert-if-true-tag.md) and [@phan-assert-if-true](phan-assert-if-true-tag.md), which restate the same
+assertion for their respective tools.
 
 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).

docs/Writerside/topics/phpdoc/tags/psalm-assert-tag.md

@@ -1,22 +1,24 @@
 # @psalm-assert
 
 <primary-label ref="phpdoc-component"/>
-<secondary-label ref="not-implemented"/>
 
 The `@psalm-assert` tag asserts that an argument or variable is
 narrowed to a given type after the call returns. It is defined by
 the static analyzer Psalm.
 
 ```
-"@psalm-assert" <Type> <Variable>
+"@psalm-assert" <Type> <Variable> [ <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-assert` tag produces an `AssertTag` instance, carrying the
+asserted `$type` and `$variable` alongside the `$name` and optional
+`$description` every [Tag](phpdoc.md#tag) already provides.
+
+```php
+final class AssertTag extends TypedVariableTag {}
+```
+
+The same `AssertTag` is produced by [@phpstan-assert](phpstan-assert-tag.md) and [@phan-assert](phan-assert-tag.md), which restate the same
+assertion for their respective tools.
 
 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).