Php-cs-fixer: PhpdocOrderFixer - order?

[keradus]

Current PhpdocOrderFixer produce the following order:

/**
 * @param
 *
 * @throws
 *
 * @return
 */

What is the reason of keeping that order, not the param-return-throws ? Is is standardized by PSR?

[keradus]

cc @GrahamCampbell

[keradus]

btw
Files that does not follow that order for Symfony repo (2.3 branch) - 224.
Files that does not follow param-return-throws order - 18.

[GrahamCampbell]

param-throws-return is implied by PSR-5

[GrahamCampbell]

It also makes sense to me because you throw before you return. ;)

[keradus]

param-throws-return is implied by PSR-5

could you ref that?

[GrahamCampbell]

All their examples are in that order, I think?

[keradus]

I can see only _one_ example with @return and @throws annotations.
And nothing in text about it.

[GrahamCampbell]

Well, even if all their examples constitutes one example, that's still all of them. I also never said it was written in words. It's just inferred.

[keradus]

Damn it... it would be great to standardize it on PSR level

[GrahamCampbell]

It might be cool to make this configurable though.

[GrahamCampbell]

I personally think symfony should change it's order though. ;P

[keradus]

Think so too. That is why I asked for any refs ;)

[GrahamCampbell]

I assume symfony has that order, because that would be the lexical order.

[GrahamCampbell]

Where does symfony put deprecated tags though? Is that in lexical order, just any order?

[GrahamCampbell]

Maybe we just need a new fixer, that puts all tags in lexical order?

[keradus]

I would :-1: for that

[GrahamCampbell]

Well, why just order those 3 tags, when you could define an ordering for every tag, if symfony does actually have such an ordering.

[keradus]

:-1: for order tags in alpha order.
:+1: for order tags in arbitrary order (which may be configured in alpha, but also in different, even custom, eg allowing to pass a list showing the order or function to compare two tags which one should be first)

[keradus]

Conclusion:
configuration is required for a fixer, which specifies which tags should be ordered using what order.

Anyone willing to help with it is more than welcome.

[localheinz]

What is the reason of keeping that order, not the param-return-throws ? Is is standardized by PSR?

I think a valid reason for the existing order is this

• a method has input (@param)
• a method has ouput (@return)
• something can go wrong _after_ accepting the input and _before_ returning the output; an exception can be thrown (@throws)

Not sure of that was the reasoning behind it, or if @mvriel wants to chime in (sorry!), but I can imagine that this could well be it.

For reference, see

• https://phpdoc.org/docs/latest/references/phpdoc/tags/throws.html#examples
• https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#719-throws

[SpacePossum]

How about the fixer also order @param annotations based on the method/function signature (this order is as proposed in the discussion in https://github.com/FriendsOfPHP/PHP-CS-Fixer/pull/2385)?

[keradus]

I would rather have 2 fixers:

• one to sort different annotations order, keeping order of same annotations, here, sorting order is defined by user
• sort param annotations, order is defined by function prototype

one may run later, but not first rule

[UksusoFF]

Any updates for this?

[kubawerlos]

@UksusoFF can you check if this PhpdocParamOrderFixer works for you? If so I'd make a PR to add it here.

[UksusoFF]

@UksusoFF can you check if this PhpdocParamOrderFixer works for you? If so I'd make a PR to add it here.

This works but only with @param.