phpDoc variable, attribute, param possible value suggestion

[aurimasniekis]

Hello,

I would like to suggest to make possible values list for @param, @Property and etc phpDoc tags it would really help on autocompleting in normal IDE like PHPStorm. Kinda like this:

@param ["Type"] [name] [possible values] [<description>]

Example What I imagine:

/**
 * @param string $type (img,article,link) Element type
 */
public function getElement($type);

Real life example is PHPStorm Symfony2 Plugin which suggest possible values for container, route, doctrine repositories, entities and other thing by tagging function param with special tag.

[ashnazg]

This sounds to me like how an IDE implementation would behave based on autocompletion of tag writing... and thus doesn't involve the spec itself.

Ping @ondrejmirtes @muglug @neuro159 @mindplay-dk @GaryJones @mvriel @jaapio for opinions... does it sound this way to you?

[TysonAndre]

Somewhat related: Phan and Psalm both have support for @param 'img'|'article'|'link' $type Element type (both literal int types and literal string types)

• Psalm also supports references to class constants
• Phan supports hex escapes when parsing and converting back to string to avoid ambiguity for special characters (e.g. @param '\\x3c\\x3d\\x3e\\x0a' $x means a function would allow "<=>\n" as an argument
• This is an alternate way for IDEs to get the information they would need for autocompletion
• If you want to keep the scope of PSRs small, this can be postponed

https://github.com/vimeo/psalm/blob/master/docs/typing_in_psalm.md#specifying-stringint-options-aka-enums
https://github.com/phan/phan/wiki/About-Union-Types

[GaryJones]

I'd be open to looking more into the 'a'|'b' format, though I do wonder how much of the code would then be being duplicated in the docs.

[neuro159]

This is an old feature request for PhpStorm - https://youtrack.jetbrains.com/issue/WI-854 - and we are finally working to make it happen (one way or another).

We have planned to make use of parameterized types, something like
@param int<_enum<"CURL_HTTP_VERSION_*">> $version One of ...
This will pre-filer completion list for this param and raise the warning in case of unknown value used.
_enum is one of the useful contract descriptions. Would be great to have a generic syntax for all sorts of type assertions (including stuff inferred from loops and conditionals - more than 0, not instanceof X etc) , but this is a topic worth its own discussion.

[muglug]

I'd be open to looking more into the 'a'|'b' format, though I do wonder how much of the code would then be being duplicated in the docs.

In my experience, not terribly much in the places we use this syntax in Vimeo’s codebase.

Often it’s just an explicit form of an existing docblock comment:
@param string $foo One of 'a', 'b' or 'c'
becomes
@param 'a'|'b'|'c' $foo

[ashnazg]

Hmm, so allowing for literals and constants in areas where we currently limit it to types and classes... almost always in a union string, but for simplicity can perhaps just open all the type/class areas up to allow literals/constants.

Any concerns with this approach?

[JanTvrdik]

In theory we MAY allow everything that's considered constant value in PHP (*). This would allow for example to use constant references as well, i.e. sth like @param self::FOO|self::BAR.

Global constants would conflict with class names, so probably only class constants could be allowed.

(*) See PHPStan's ABNF grammar for constant expression

[ashnazg]

If this needs to be pursued further, please bring this up as a new thread on the FIG mailing list for discussion -- https://groups.google.com/forum/#!forum/php-fig