Common prefix for phpdoc tags containing "new" (non-standard) phpdoc
TysonAndre opened this issue · 3 comments
Many union types that are commonly used are not part of an official phpdoc standard or PSR-5, which (is being worked on by the php community and tooling authors but) has been a draft for years (?T, true, false, array<T>, array<K, T>, list<T>, T&U, etc.)
As a result, many tools don't support them - e.g. I've seen that phpstorm has an open ticket for array<..>: https://youtrack.jetbrains.com/issue/WI-6558
- PHPStorm does support some of these, though -
ArrayObject<K, V>,iterable<...>, and intersection types: https://blog.jetbrains.com/phpstorm/2018/09/phpstorm-2018-3-eap-183-2635-12/
For users, it would be convenient to have two sets of tags:
@x-param array<int, T> $x- to be used by all tools supporting non-standard phpdoc@param T[] $x, to be supported by tools only supporting standard phpdoc or a more limited subset.
The approach of reading tags meant for other analyzers/IDEs (e.g. a phpstan plugin reading tags for psalm) may cause problems or repetition - While it's usually useful, the tag may have been added for a given plugin, or to work around a false positive only affecting one analyzer/IDE.
Related to #3 and phpstan/phpstan#2223
My best idea is to use a prefix such as @x- everywhere (experimental). Other possibilities: @new-, etc, but it would only be useful if there were plans to support it in more than one tool.
cc @ondrejmirtes @muglug @staabm
e.g. @x-param, @x-return, @x-property, @x-method, etc.
Hi,
I don't think this is something that needs to change from the status quo, i.e. it's a solved problem.
Each tool has a different feature set - it supports a different subset of types. And each user uses different subset of the available tools, so each user has different preferences.
How it works today (in my eyes) - you can write everything in normal PHPDoc tags like @param, @var etc. as long as all the tools you use understand it. If you use multiple partially overlapping tools, you can write the lowest common denominator in @param and then a specific thing in @phpstan-param and @psalm-param.
Adding something like @x-param that everyone should use for advanced types isn't a viable solution as the ecosystem is in flux all the time, so there's a fragmentation of what each tool supports, we'd again have to come up with a subset that each tool that understands @x-, so we actually wouldn't dug out of a hole at all...
I just want to add how cross-tool functionality works - PHPStan reads @psalm- tags and can interpret most types in it, but if it stumbles upon something that the PHPDoc parser cannot parse, or some unknown type, it silently skips it, and just uses the thing from @param.
If you use multiple partially overlapping tools, you can write the lowest common denominator in @param and then a specific thing in @phpstan-param and @psalm-param.
I'm aware of that, but disliked the repetition - you'd potentially have to write 2 or 3 (or more) different tags (phan-, phpstan-, psalm-), or have other tools use a tag that was possibly intended by an application/library author be specific to one tool
I just want to add how cross-tool functionality works - PHPStan reads @psalm- tags and can interpret most types in it, but if it stumbles upon something that the PHPDoc parser cannot parse, or some unknown type, it silently skips it, and just uses the thing from @param.
That sounds like the most reasonable way, but long-term seems like it would end up with various tools using @psalm-param the same way I'm proposing to use @x-param, except without visibility into phpdoc errors
Also, psalm has some psalm-specific functionality such as @psalm-type TaggedCodeType = array<int, array{0: int, 1: string}>, but I assume you mean by " some unknown type" that no unknown class warning gets emitted.
so there's a fragmentation of what each tool supports,
There'd be the benefit that you'd know the tool was written in 2020 or later and the authors were aware of the new type syntaxes, especially if common functionality was documented.