PSR-19 PHPDoc Tags @param should not have optional name

Skip to first unread message

Ben Mewburn

Oct 4, 2019, 8:51:03 PM10/4/19
to PHP Framework Interoperability Group

PSR-19 states that for @param:

> The "name" is required only when some @param tags are omitted due to all useful info already being visible in the code signature itself

I think this should be changed to always required or, alternatively:

always required when there is more than one parameter.

Currently it's ambiguous. Is the below ok? There are no param tags omitted below but then it implies order.

* @param int description
* @param string description
foo(int $a, string $b);

Or this? No omissions again. No implicit order though.
* @param int $a description
* @param string description
foo($a, $b);

The only case it seems relevant to is when there is only a single parameter.
In which case it should be stated as such. It would then be consistent with @var.

* @param int description

However, given that there's been some talk about making type optional because it can be declared. You could end up with this.

* @param description
foo(int $a);

Which would likely make it difficult for parsers to make sense of. Making name always required to me seems the least complex and most future proof way to spec this.

Kind regards
Reply all
Reply to author
0 new messages