Add immutable and not-deprecated tags

Author: SerafimArts

Writerside/tl.tree

@@ -63,13 +63,13 @@
     </toc-element>
 
     <toc-element topic="phpdoc.md" toc-title="PHPDoc Parser">
-        <toc-element toc-title="Standard Tags">
+        <toc-element toc-title="Standard Tags" topic="standard-tags.md">
             <toc-element topic="abstract-tag.md" />
             <toc-element topic="api-tag.md" />
             <toc-element topic="deprecated-tag.md" />
             <toc-element topic="extends-tag.md" />
             <toc-element topic="final-tag.md" />
-            <toc-element topic="immutable-tag.md" wip="true" />
+            <toc-element topic="immutable-tag.md" />
             <toc-element topic="implements-tag.md" />
             <toc-element topic="inherits-tag.md" />
             <toc-element topic="internal-tag.md" />
@@ -96,14 +96,12 @@
             <toc-element topic="template-use-tag.md" />
             <toc-element topic="throws-tag.md" />
             <toc-element topic="throw-tag.md" />
-            <toc-element topic="todo-tag.md" />
             <toc-element topic="use-tag.md" />
             <toc-element topic="var-tag.md" />
-            <toc-element topic="version-tag.md" />
         </toc-element>
-        <toc-element toc-title="Advanced Tags">
+        <toc-element toc-title="Advanced Tags" topic="advanced-tags.md">
             <toc-element topic="no-named-arguments-tag.md" />
-            <toc-element topic="not-deprecated-tag.md" wip="true" />
+            <toc-element topic="not-deprecated-tag.md" />
             <toc-element topic="param-closure-this-tag.md" />
             <toc-element topic="param-immediately-invoked-callable-tag.md" />
             <toc-element topic="param-later-invoked-callable-tag.md" />
@@ -114,7 +112,7 @@
             <toc-element topic="suppress-tag.md" />
             <toc-element topic="unused-param-tag.md" />
         </toc-element>
-        <toc-element toc-title="phpDocumentor">
+        <toc-element toc-title="phpDocumentor" topic="phpdocumentor-tags.md">
             <toc-element topic="access-tag.md" />
             <toc-element topic="author-tag.md" />
             <toc-element topic="category-tag.md" />
@@ -134,11 +132,13 @@
             <toc-element topic="staticvar-tag.md" />
             <toc-element topic="subpackage-tag.md" />
             <toc-element topic="toc-tag.md" wip="true" />
+            <toc-element topic="todo-tag.md" />
             <toc-element topic="tutorial-tag.md" wip="true" />
             <toc-element topic="used-by-tag.md" />
             <toc-element topic="uses-tag.md" />
+            <toc-element topic="version-tag.md" />
         </toc-element>
-        <toc-element toc-title="Psalm">
+        <toc-element toc-title="Psalm" topic="psalm-tags.md">
             <toc-element topic="psalm-allow-private-mutation-tag.md" wip="true" />
             <toc-element topic="psalm-api-tag.md" wip="true" />
             <toc-element topic="psalm-assert-tag.md" wip="true" />
@@ -202,7 +202,7 @@
             <toc-element topic="psalm-variadic-tag.md" wip="true" />
             <toc-element topic="psalm-yield-tag.md" wip="true" />
         </toc-element>
-        <toc-element toc-title="PHPStan">
+        <toc-element toc-title="PHPStan" topic="phpstan-tags.md">
             <toc-element topic="phpstan-allow-private-mutation-tag.md" wip="true" />
             <toc-element topic="phpstan-assert-tag.md" wip="true" />
             <toc-element topic="phpstan-assert-if-false-tag.md" wip="true" />
@@ -243,7 +243,7 @@
             <toc-element topic="phpstan-var-tag.md" wip="true" />
             <toc-element topic="phpstan-yield-tag.md" wip="true" />
         </toc-element>
-        <toc-element toc-title="Phan">
+        <toc-element toc-title="Phan" topic="phan-tags.md">
             <toc-element topic="phan-abstract-tag.md" wip="true" />
             <toc-element topic="phan-assert-tag.md" wip="true" />
             <toc-element topic="phan-assert-false-condition-tag.md" wip="true" />
@@ -284,14 +284,14 @@
             <toc-element topic="phan-write-only-tag.md" wip="true" />
             <toc-element topic="phanclosurescope-tag.md" wip="true" />
         </toc-element>
-        <toc-element toc-title="PhpStorm">
+        <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="formatter-off-tag.md" wip="true" />
             <toc-element topic="formatter-on-tag.md" wip="true" />
         </toc-element>
-        <toc-element toc-title="PHP CodeSniffer">
+        <toc-element toc-title="PHP CodeSniffer" topic="phpcs-tags.md">
             <toc-element topic="phpcs-suppress-tag.md" wip="true" />
             <toc-element topic="coding-standards-ignore-start-tag.md" wip="true" />
             <toc-element topic="coding-standards-ignore-end-tag.md" wip="true" />

Writerside/topics/phpdoc/advanced-tags.md

@@ -0,0 +1,58 @@
+# Advanced Tags
+
+<primary-label ref="phpdoc-component"/>
+<show-structure for="chapter" depth="2"/>
+
+The **Advanced Tags** are a small set of tags that were originally
+introduced by individual static analyzers — chiefly Psalm and PHPStan — to
+express things the classic phpDocumentor vocabulary never covered: purity,
+by-reference output parameters, how a closure is invoked, whether a class
+may grow magic members. Over time these spellings became common enough that
+both analyzers came to accept them **without a vendor prefix**, and that is
+exactly how they are grouped here.
+
+In other words, this is the vendor-neutral middle ground: less universal
+than the [Standard Tags](standard-tags.md), but no longer tied to a single
+tool's `@psalm-*` or `@phpstan-*` namespace either. You write
+`@param-out`, not `@psalm-param-out`; `@pure-unless-callable-is-impure`, not
+its prefixed form.
+
+## What Belongs Here
+
+* **Purity and side effects** —
+  [@pure-unless-callable-is-impure](pure-unless-callable-is-impure-tag.md),
+  which marks a function pure except when a callable it is handed is itself
+  impure.
+* **By-reference output** — [@param-out](param-out-tag.md), describing the
+  type a parameter *holds after* the call rather than the type it accepts.
+* **How a callable is invoked** —
+  [@param-closure-this](param-closure-this-tag.md) binds the `$this` a
+  closure parameter runs against, while
+  [@param-immediately-invoked-callable](param-immediately-invoked-callable-tag.md)
+  and
+  [@param-later-invoked-callable](param-later-invoked-callable-tag.md)
+  distinguish a callback called before the function returns from one stored
+  for later.
+* **Sealing magic members** — [@seal-methods](seal-methods-tag.md) and
+  [@seal-properties](seal-properties-tag.md) forbid a class from resolving
+  any magic member not explicitly declared.
+* **Diagnostics** — [@suppress](suppress-tag.md) silences named issues on an
+  element, and [@unused-param](unused-param-tag.md) marks a parameter kept
+  only for signature compatibility.
+* **Calling conventions** —
+  [@no-named-arguments](no-named-arguments-tag.md) declares that a function
+  must not be called with named arguments, and
+  [@not-deprecated](not-deprecated-tag.md) asserts an element is explicitly
+  *not* deprecated despite what surrounding code might suggest.
+
+<note>
+Each of these tags still has a prefixed twin under a specific analyzer —
+<code>@psalm-param-out</code>, <code>@phpstan-pure</code>, and so on — listed
+under that analyzer's own group in the sidebar. The bare spellings collected
+here are the ones both major analyzers agree to read without a prefix.
+</note>
+
+Like the standard set, every tag in this group is fully recognized: it
+parses into a dedicated, typed object, with any type it carries read through
+the same [TypeLang grammar](introduction.md) used everywhere else. Open any
+entry in the sidebar for its grammar, resulting object, and examples.

Writerside/topics/phpdoc/phan-tags.md

@@ -0,0 +1,47 @@
+# Phan Tags
+
+<primary-label ref="phpdoc-component"/>
+<show-structure for="chapter" depth="2"/>
+
+The **Phan Tags** are the annotations that belong to
+[Phan](https://github.com/phan/phan)'s own vocabulary, written under its
+`@phan-*` vendor prefix. Phan uses the prefix much as Psalm and PHPStan do:
+to add analyzer-specific capabilities — line-scoped suppression, real vs.
+documented return types, magic-member policing — and to offer a Phan-scoped
+override of a tag that also exists in the shared convention.
+
+A prefixed tag that mirrors one documented elsewhere — `@phan-param` beside
+[@param](param-tag.md), `@phan-return` beside [@return](return-tag.md) —
+means the same thing as the plain spelling; the prefix only marks it as the
+one Phan should trust.
+
+## What This Group Covers
+
+* **Assertions** — `@phan-assert`, `@phan-assert-true-condition`,
+  `@phan-assert-false-condition`, `@phan-assert-if-true`,
+  `@phan-assert-if-false`.
+* **Line-scoped suppression** — `@phan-suppress-current-line`,
+  `@phan-suppress-next-line`, `@phan-suppress-next-next-line`,
+  `@phan-suppress-previous-line`, and the file-wide `@phan-file-suppress`.
+* **Return types** — `@phan-real-return`, `@phan-hardcode-return-type`,
+  distinguishing the type Phan should infer from the one it should report.
+* **Magic-member policy** — `@phan-forbid-undeclared-magic-methods`,
+  `@phan-forbid-undeclared-magic-properties`,
+  `@phan-read-only`, `@phan-write-only`.
+* **Purity and immutability** — `@phan-pure`, `@phan-side-effect-free`,
+  `@phan-immutable`, `@phan-constructor-used-for-side-effects`.
+* **Prefixed overrides** — `@phan-var`, `@phan-param`, `@phan-return`,
+  `@phan-property`, `@phan-method`, `@phan-template`, `@phan-mixin`,
+  `@phan-extends`, and the rest, each shadowing its unprefixed counterpart
+  for Phan specifically.
+
+<warning>
+The tags in this group are listed for reference only. They are catalogued so
+the vocabulary is documented in one place, but are <b>not yet recognized</b>
+by the parser — a docblock containing one currently falls back to a plain
+<a href="phpdoc.md#tag">Tag</a>. Their pages are marked work-in-progress in
+the sidebar.
+</warning>
+
+For the authoritative definitions, see
+[Phan's annotating-your-source-code guide](https://github.com/phan/phan/wiki/Annotating-Your-Source-Code).

Writerside/topics/phpdoc/phpcs-tags.md

@@ -0,0 +1,42 @@
+# PHP CodeSniffer Tags
+
+<primary-label ref="phpdoc-component"/>
+<show-structure for="chapter" depth="2"/>
+
+The **PHP CodeSniffer Tags** are the annotations
+[PHP_CodeSniffer](https://github.com/PHPCSStandards/PHP_CodeSniffer)
+recognizes to turn its own rules on and off inside a file. Unlike every other
+group in this section, these tags have nothing to do with types or
+documentation at all — they are coding-standard directives, telling the
+sniffer to skip a line, a block, or a whole file when checking style.
+
+They come in two spellings: the modern `@phpcs:` form and the older
+`@codingStandardsIgnore*` family kept for backward compatibility with rules
+written against earlier PHP_CodeSniffer releases.
+
+## What This Group Covers
+
+* **Scoped suppression (modern)** — [@phpcs:suppress](phpcs-suppress-tag.md),
+  disabling one or more named sniffs for the following statement.
+* **Region suppression (legacy)** —
+  [@codingStandardsIgnoreStart](coding-standards-ignore-start-tag.md) and
+  [@codingStandardsIgnoreEnd](coding-standards-ignore-end-tag.md) bracket a
+  block the sniffer should skip, while
+  [@codingStandardsIgnoreLine](coding-standards-ignore-line-tag.md) skips a
+  single line and
+  [@codingStandardsIgnoreFile](coding-standards-ignore-file-tag.md) exempts
+  the entire file.
+* **General marker** —
+  [@codingStandards](coding-standards-tag.md), the bare root of that legacy
+  family.
+
+<warning>
+The tags in this group are listed for reference only. They are catalogued so
+the vocabulary is documented in one place, but are <b>not yet recognized</b>
+by the parser — a docblock containing one currently falls back to a plain
+<a href="phpdoc.md#tag">Tag</a>. Their pages are marked work-in-progress in
+the sidebar.
+</warning>
+
+For the authoritative behavior, see
+[PHP_CodeSniffer's wiki on ignoring code](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Advanced-Usage#ignoring-parts-of-a-file).

Writerside/topics/phpdoc/phpdocumentor-tags.md

@@ -0,0 +1,52 @@
+# phpDocumentor Tags
+
+<primary-label ref="phpdoc-component"/>
+<show-structure for="chapter" depth="2"/>
+
+The **phpDocumentor Tags** are the tags that originate with
+[phpDocumentor](https://www.phpdoc.org) itself — the documentation
+generator that defined the original PHPDoc convention long before the
+current generation of static analyzers existed. Where the
+[Standard](standard-tags.md) and [Advanced](advanced-tags.md) groups collect
+tags about *types*, this group collects tags about *documentation*:
+authorship, licensing, packaging, cross-references, and the prose that ends
+up in a generated API manual.
+
+Many of these predate modern type analysis and carry no type information at
+all — they annotate the human-facing documentation rather than constrain the
+code. They are grouped here by provenance, and a fair number are legacy
+entries from phpDocumentor 1.x kept for compatibility with older docblocks.
+
+## What Belongs Here
+
+* **Authorship and legal** — [@author](author-tag.md),
+  [@copyright](copyright-tag.md), [@license](license-tag.md).
+* **Packaging and structure** — [@package](package-tag.md),
+  [@subpackage](subpackage-tag.md), [@category](category-tag.md),
+  [@name](name-tag.md), [@global](global-tag.md),
+  [@staticvar](staticvar-tag.md), and the plain [@static](static-tag.md).
+* **Cross-references** — [@uses](uses-tag.md) and its reverse
+  [@used-by](used-by-tag.md).
+* **Versioning and lifecycle** — [@version](version-tag.md) records an
+  element's own version, [@since](since-tag.md) the version it first
+  appeared in, and [@todo](todo-tag.md) notes work still to be done.
+* **Documentation control** — [@inheritdoc](inheritdoc-tag.md) pulls
+  documentation down from a parent, [@ignore](ignore-tag.md) hides an
+  element from the generated output, and [@access](access-tag.md) is the
+  legacy way of recording visibility.
+* **Examples and sources** — [@example](example-tag.md),
+  [@source](source-tag.md), and [@filesource](filesource-tag.md) embed or
+  point to code in the rendered documentation.
+
+<note>
+Several of these tags — <a href="access-tag.md">@access</a>,
+<a href="staticvar-tag.md">@staticvar</a>, <a href="name-tag.md">@name</a> —
+belong to the classic phpDocumentor 1.x vocabulary and have been dropped from
+phpDocumentor 3's current reference. They are still parsed here so that
+docblocks written against the older toolchain keep working.
+</note>
+
+The implemented tags in this group each parse into a dedicated object; a few
+entries (such as [@id](id-tag.md), [@toc](toc-tag.md), and
+[@tutorial](tutorial-tag.md)) are still marked work-in-progress. Open any
+entry in the sidebar for its exact grammar and behavior.

Writerside/topics/phpdoc/phpstan-tags.md

@@ -0,0 +1,53 @@
+# PHPStan Tags
+
+<primary-label ref="phpdoc-component"/>
+<show-structure for="chapter" depth="2"/>
+
+The **PHPStan Tags** are the annotations that belong to
+[PHPStan](https://phpstan.org)'s own vocabulary, written under its
+`@phpstan-*` vendor prefix. As with Psalm, the prefix serves two roles: it
+introduces PHPStan-specific features — assertions, its `@phpstan-ignore`
+family of diagnostic suppressors, type aliases — and it provides a
+PHPStan-scoped override of a tag that also exists unprefixed, letting a
+project refine a type *for PHPStan only*.
+
+A prefixed tag that mirrors one documented elsewhere — `@phpstan-param`
+beside [@param](param-tag.md), `@phpstan-return` beside
+[@return](return-tag.md) — carries the same meaning as the plain spelling;
+the prefix simply tells PHPStan to prefer this line when it and another tool
+disagree.
+
+## What This Group Covers
+
+* **Assertions** — `@phpstan-assert`, `@phpstan-assert-if-true`,
+  `@phpstan-assert-if-false`.
+* **Diagnostic suppression** — the `@phpstan-ignore` family
+  (`@phpstan-ignore`, `@phpstan-ignore-line`, `@phpstan-ignore-next-line`).
+* **Purity and immutability** — `@phpstan-pure`, `@phpstan-impure`,
+  `@phpstan-immutable`, `@phpstan-readonly`,
+  `@phpstan-pure-unless-callable-is-impure`.
+* **Type aliases and generics** — `@phpstan-type`, `@phpstan-import-type`,
+  `@phpstan-template` (with its covariant and contravariant forms).
+* **Prefixed overrides** — `@phpstan-param`, `@phpstan-return`,
+  `@phpstan-var`, `@phpstan-property`, `@phpstan-method`,
+  `@phpstan-param-out`, `@phpstan-self-out`, and the rest, each shadowing
+  its unprefixed counterpart for PHPStan specifically.
+
+<note>
+Many capabilities PHPStan shares with Psalm are recognized here without a
+prefix — see <a href="advanced-tags.md">Advanced Tags</a> for the
+vendor-neutral spellings such as
+<a href="param-out-tag.md">@param-out</a> and
+<a href="pure-unless-callable-is-impure-tag.md">@pure-unless-callable-is-impure</a>.
+</note>
+
+<warning>
+The tags in this group are listed for reference only. They are catalogued so
+the vocabulary is documented in one place, but are <b>not yet recognized</b>
+by the parser — a docblock containing one currently falls back to a plain
+<a href="phpdoc.md#tag">Tag</a>. Their pages are marked work-in-progress in
+the sidebar.
+</warning>
+
+For the authoritative definitions, see
+[PHPStan's PHPDoc reference](https://phpstan.org/writing-php-code/phpdocs-basics).

Writerside/topics/phpdoc/phpstorm-tags.md

@@ -0,0 +1,42 @@
+# PhpStorm Tags
+
+<primary-label ref="phpdoc-component"/>
+<show-structure for="chapter" depth="2"/>
+
+The **PhpStorm Tags** are the annotations that
+[PhpStorm](https://www.jetbrains.com/phpstorm/) understands as directives to
+the IDE itself rather than to a command-line analyzer. They do not describe
+types or generate documentation; they change how the editor treats the
+surrounding code — suppressing an inspection, injecting a language into a
+string, marking a call as one that is expected to throw.
+
+Because they steer editor behavior, these tags have no vendor prefix in the
+`@psalm-*` sense: they are spelled as ordinary tags (`@noinspection`,
+`@language`) that happen to be meaningful only inside JetBrains tooling.
+
+## What This Group Covers
+
+* **Inspection control** — [@noinspection](noinspection-tag.md), which
+  silences one or more named IDE inspections for the element that follows.
+* **Language injection** — [@language](language-tag.md), telling the editor
+  that a string or heredoc contains another language (SQL, JSON, regexp)
+  so it can be highlighted and analyzed accordingly.
+* **Test expectations** —
+  [@expected-exception](expected-exception-tag.md), recording the exception
+  a test is expected to raise.
+* **Formatter control** — [@formatter:off](formatter-off-tag.md) and
+  [@formatter:on](formatter-on-tag.md), bracketing a region the reformatter
+  should leave untouched.
+
+<warning>
+The tags in this group are listed for reference only. They are catalogued so
+the vocabulary is documented in one place, but are <b>not yet recognized</b>
+by the parser — a docblock containing one currently falls back to a plain
+<a href="phpdoc.md#tag">Tag</a>. Their pages are marked work-in-progress in
+the sidebar.
+</warning>
+
+For the authoritative behavior, see
+[PhpStorm's documentation on suppressing inspections](https://www.jetbrains.com/help/phpstorm/disabling-and-enabling-inspections.html)
+and its
+[language injection guide](https://www.jetbrains.com/help/phpstorm/using-language-injections.html).