Php_codesniffer: Rules about ordering/grouping annotations in phpdoc?

[stephanvierkant]

I've used phpcs to get rid of many useless @param comments. Those lines have been removed and now my docblock looks like this:

/**
 *
 *
 * @Route("/{id}/add", name="entity_add")
 *
 * @Method({"GET", "POST"})
 *
 *
 *
 * @return array|JsonResponse
 *
 * @Template()
 *
 */

There are multiple problems with it and I'd like to use phpcs to fix them automatically. This is the expected output:

/**
 * @Route("/{id}/add", name="entity_add")
 * @Method({"GET", "POST"})
 * @Template()
 *
 * @return array|JsonResponse
 */

Let's brake down this example by some rules:

• Group Route, Method and Template, since they all are in the same namespace (Sensio\Bundle\FrameworkExtraBundle\Configuration\). Multiple @param lines should be grouped the same way.
• Exactly one empty line between namespaces (like my example) or between different annotations (also one line between @Route and @Method).
• No empty lines at begin or end of the docblock. Done by Generic.Commenting.DocComment or SlevomatCodingStandard.Commenting
• The order of the annotations should be configurable. In my controllers I'd like to have the Configuration annotations first and @return last, but for entities I'd like to have @var first, then @ORM\ and then @Assert\, @Serializer\, @Gedmo, etc.

Are any of these rules already available somewhere in the phpcs-world? I can find some of them in the Symfony rules, but that would require using php-cs-fixer.

[gsherwood]

There aren't any included docblock sniffs that will achieve what you want and I'm not sure if there are any custom sniffs floating around for this. You probably need one that has settings for the allowed groupings and ordering of tags.

The most you can get from PHPCS right now is Additional blank lines found at end of doc comment by using Generic.Commenting.DocComment.SpacingAfter.

[stephanvierkant]

Thanks! I'm now using SlevomatCodingStandard\Sniffs\Commenting, that removed all empty lines. Generic.Commenting.DocComment would help too. Not exactly what I wanted, but no empty lines is better than many empty lines.

[gsherwood]

Closing. If there are sniffs you think would be generically useful that you can't find, you could submit a feature request with details.