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

26 views
Skip to first unread message

Ben Mewburn

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

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
*/
foo($a);

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
Ben
Reply all
Reply to author
Forward
0 new messages