Skip to content

Commit 1201077

Browse files
SerafimArtsSerafimArts
committed
Add additional platforms support for DocBlockParser::createDefault() method in docs
1 parent 06bb311 commit 1201077

6 files changed

Lines changed: 88 additions & 31 deletions

File tree

‎Writerside/topics/phpdoc/custom-tags.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -147,9 +147,16 @@ The built-in <code>StandardPlatform</code> is always loaded first, so every
147147
standard tag stays available; a platform passed in only adds to it, or overrides
148148
an entry when it reuses a name. The other built-in families (phpDocumentor,
149149
Psalm, PHPStan, Phan, PhpStorm, PHP CodeSniffer) are <b>not</b> loaded by the
150-
constructor — list them alongside your own platform when you need them, or see
151-
<a href="platforms.md"><code>DocBlockParser::createDefault()</code></a> for the
152-
full built-in set.
150+
constructor. To get the full built-in set together with your own platform, pass
151+
it to
152+
<a href="platforms.md"><code>DocBlockParser::createDefault()</code></a> via its
153+
<code>$additionalPlatforms</code> argument:
154+
155+
<code-block lang="php">
156+
$parser = DocBlockParser::createDefault(additionalPlatforms: [
157+
new MoneyPlatform(),
158+
]);
159+
</code-block>
153160
</note>
154161

155162
## Where to Go Next

‎Writerside/topics/phpdoc/phan-tags.md‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -35,12 +35,30 @@ one Phan should trust.
3535
`@phan-extends`, and the rest, each shadowing its unprefixed counterpart
3636
for Phan specifically.
3737

38+
<note>
39+
Nearly every tag in this group is recognized once the <b>Phan</b> platform is
40+
enabled. It ships with the library as <code>PhanPlatform</code> and is loaded by
41+
the <a href="platforms.md"><code>DocBlockParser::createDefault()</code></a>
42+
factory:
43+
44+
<code-block lang="php">
45+
$parser = DocBlockParser::createDefault();
46+
</code-block>
47+
48+
Alternatively, pass <code>new PhanPlatform()</code> to the parser constructor to
49+
add it on top of the standard tags. A bare <code>new DocBlockParser()</code>
50+
loads the standard platform only, so an unrecognized <code>@phan-*</code> tag
51+
then falls back to a plain <a href="phpdoc.md#tag">Tag</a>.
52+
</note>
53+
3854
<warning>
39-
The tags in this group are listed for reference only. They are catalogued so
40-
the vocabulary is documented in one place, but are <b>not yet recognized</b>
41-
by the parser — a docblock containing one currently falls back to a plain
42-
<a href="phpdoc.md#tag">Tag</a>. Their pages are marked work-in-progress in
43-
the sidebar.
55+
Two assertion tags in this group are not yet recognized —
56+
<a href="phan-assert-true-condition-tag.md">@phan-assert-true-condition</a> and
57+
<a href="phan-assert-false-condition-tag.md">@phan-assert-false-condition</a>.
58+
A docblock containing either currently falls back to a plain
59+
<a href="phpdoc.md#tag">Tag</a>. The shorter forms
60+
<code>@phan-assert</code>, <code>@phan-assert-if-true</code> and
61+
<code>@phan-assert-if-false</code> are fully supported.
4462
</warning>
4563

4664
For the authoritative definitions, see

‎Writerside/topics/phpdoc/phpcs-tags.md‎

Lines changed: 16 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -30,13 +30,22 @@ written against earlier PHP_CodeSniffer releases.
3030
[@codingStandards](coding-standards-tag.md), the bare root of that legacy
3131
family.
3232

33-
<warning>
34-
The tags in this group are listed for reference only. They are catalogued so
35-
the vocabulary is documented in one place, but are <b>not yet recognized</b>
36-
by the parser — a docblock containing one currently falls back to a plain
37-
<a href="phpdoc.md#tag">Tag</a>. Their pages are marked work-in-progress in
38-
the sidebar.
39-
</warning>
33+
<note>
34+
Every tag in this group is recognized once the <b>PHP CodeSniffer</b> platform
35+
is enabled. It ships with the library as <code>PhpCodeSnifferPlatform</code> and
36+
is loaded by the
37+
<a href="platforms.md"><code>DocBlockParser::createDefault()</code></a> factory:
38+
39+
<code-block lang="php">
40+
$parser = DocBlockParser::createDefault();
41+
</code-block>
42+
43+
Alternatively, pass <code>new PhpCodeSnifferPlatform()</code> to the parser
44+
constructor to add it on top of the standard tags. A bare
45+
<code>new DocBlockParser()</code> loads the standard platform only, so an
46+
unrecognized <code>@phpcs:*</code> or <code>@codingStandards*</code> tag then
47+
falls back to a plain <a href="phpdoc.md#tag">Tag</a>.
48+
</note>
4049

4150
For the authoritative behavior, see
4251
[PHP_CodeSniffer's wiki on ignoring code](https://github.com/PHPCSStandards/PHP_CodeSniffer/wiki/Advanced-Usage#ignoring-parts-of-a-file).

‎Writerside/topics/phpdoc/phpstan-tags.md‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -41,13 +41,21 @@ vendor-neutral spellings such as
4141
<a href="pure-unless-callable-is-impure-tag.md">@pure-unless-callable-is-impure</a>.
4242
</note>
4343

44-
<warning>
45-
The tags in this group are listed for reference only. They are catalogued so
46-
the vocabulary is documented in one place, but are <b>not yet recognized</b>
47-
by the parser — a docblock containing one currently falls back to a plain
48-
<a href="phpdoc.md#tag">Tag</a>. Their pages are marked work-in-progress in
49-
the sidebar.
50-
</warning>
44+
<note>
45+
Every tag in this group is recognized once the <b>PHPStan</b> platform is
46+
enabled. It ships with the library as <code>PhpStanPlatform</code> and is loaded
47+
by the <a href="platforms.md"><code>DocBlockParser::createDefault()</code></a>
48+
factory:
49+
50+
<code-block lang="php">
51+
$parser = DocBlockParser::createDefault();
52+
</code-block>
53+
54+
Alternatively, pass <code>new PhpStanPlatform()</code> to the parser constructor
55+
to add it on top of the standard tags. A bare <code>new DocBlockParser()</code>
56+
loads the standard platform only, so an unrecognized <code>@phpstan-*</code> tag
57+
then falls back to a plain <a href="phpdoc.md#tag">Tag</a>.
58+
</note>
5159

5260
For the authoritative definitions, see
5361
[PHPStan's PHPDoc reference](https://phpstan.org/writing-php-code/phpdocs-basics).

‎Writerside/topics/phpdoc/platforms.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,8 +69,16 @@ factory:
6969
$parser = DocBlockParser::createDefault();
7070
</code-block>
7171

72-
To register your own platform on top of the built-in tool families, list them
73-
together in the constructor rather than passing yours alone.
72+
To register your own platform on top of the built-in tool families, pass it to
73+
<code>createDefault()</code> via the <code>$additionalPlatforms</code> argument —
74+
it is appended after the built-in platforms, so it extends them and overrides an
75+
entry only when it reuses the same name:
76+
77+
<code-block lang="php">
78+
$parser = DocBlockParser::createDefault(additionalPlatforms: [
79+
new MoneyPlatform(),
80+
]);
81+
</code-block>
7482
</note>
7583

7684
The definitions that end up registered are exposed as `$parser->tags` (a

‎Writerside/topics/phpdoc/psalm-tags.md‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -41,13 +41,20 @@ vendor-neutral spellings such as <a href="suppress-tag.md">@suppress</a> and
4141
<a href="param-out-tag.md">@param-out</a>.
4242
</note>
4343

44-
<warning>
45-
The tags in this group are listed for reference only. They are catalogued so
46-
the vocabulary is documented in one place, but are <b>not yet recognized</b>
47-
by the parser — a docblock containing one currently falls back to a plain
48-
<a href="phpdoc.md#tag">Tag</a>. Their pages are marked work-in-progress in
49-
the sidebar.
50-
</warning>
44+
<note>
45+
Every tag in this group is recognized once the <b>Psalm</b> platform is enabled.
46+
It ships with the library as <code>PsalmPlatform</code> and is loaded by the
47+
<a href="platforms.md"><code>DocBlockParser::createDefault()</code></a> factory:
48+
49+
<code-block lang="php">
50+
$parser = DocBlockParser::createDefault();
51+
</code-block>
52+
53+
Alternatively, pass <code>new PsalmPlatform()</code> to the parser constructor to
54+
add it on top of the standard tags. A bare <code>new DocBlockParser()</code>
55+
loads the standard platform only, so an unrecognized <code>@psalm-*</code> tag
56+
then falls back to a plain <a href="phpdoc.md#tag">Tag</a>.
57+
</note>
5158

5259
For the authoritative definitions, see
5360
[Psalm's supported annotations](https://psalm.dev/docs/annotating_code/supported_annotations/).

0 commit comments

Comments
 (0)