Php-cs-fixer: NoSuperfluousPhpdocTags - Add option to remove entries only if all superfluous

[julienfalque]

 /**
  * @param mixed $arg1
  * @param int   $arg2
  */
 function foo($arg1, $arg2) { }

-/**
- * @param mixed $arg1
- * @param mixed $arg2
- */
 function bar($arg1, $arg2) { }

~The PR that will introduce this option should also enable it on the repository as discussed in #3793.~

[SpacePossum]

maybe it should only remove the params and not the block itself? leaving that to the 'no empty doc block' rule?

[julienfalque]

Sorry the sample is misleading: yep, the fixer would only remove all annotations and leave an empty DocComment (then removed by no_empty_phpdoc).

This brings some questions though: what if all @param/@return annotations are superfluous but the DocComment also contains a summary, a description or e.g. @throws annotations? What if it contains annotations that are not PHPDoc like e.g. @dataProvider for PHPUnit?

[SpacePossum]

This brings some questions though: what if all @param/@return annotations are superfluous but the DocComment also contains a summary, a description or e.g. @throws annotations? What if it contains annotations that are not PHPDoc like e.g. @dataProvider for PHPUnit?

I would vote; remove all the @params and @return but leave the doc with the other information

[k00ni]

I got weird behavior when using PHP-CS with @Symfony enabled: it removed non-superfluous PHPDoc entries too. It started with the recent release of v2.16.0 (see entry _minor #4607 Configure no_superfluous_phpdoc_tags for Symfony (keradus)_ in the release description).

Can you please provide another example which demonstrates the benefit of the rule? I would like to understand the meaning behind the rule and to see, if i did something wrong.

[julienfalque]

The benefit of the rule is to prevent duplicated information regarding function signatures, e.g.:

/** @param int $foo */
function foo(int $foo) {}

It should not remove non-superfluous PHPDoc tags though. Are you sure they were removed by the no_superfluous_phpdoc_tags rule? If so, could you please open a new issue with more details?

[k00ni]

Thank you for the quick response.

So by your example:

/** @param int $foo */
function foo(int $foo) {}

superfluous means that int $foo is already defined with type and name in the function head itself and therefore the information in the comment above is obsolete? OK, got it.

If that is right, the observed behavior with my code is intended and PHP CS Fixer is not faulty.