Php-cs-fixer: Question: Should PhpdocAddMissingParamAnnotationFixer only add params when a docblock exists in the first place?

[localheinz]

With PHP7 and type hints as well as return type declarations, for any method that doesn't throw an exception, a docblock really doesn't add much value (opinion, of course).

Now, personally, I use this as a rule of thumb for when to have a docblock or not:

• when a method has an argument that cannot be sufficiently type hinted, a docblock helps
• when a method returns something and we cannot use return type declarations, a docblock helps
• when a method potentially throws an exception, a docblock helps
• when it needs a short and/or long description, a docblock helps

In all other cases, that is

• when a method has arguments that are sufficiently type hinted and neither throws an exception or returns something, or has sufficient return type declarations, a docblock doesn't add any value
• when a method implements a method declared on an interface where a docblock exists, a docblock

Having said that, I would still like to be able to use the phpdoc_add_missing_param_annotation fixer, but I wondered what others think: should we adjust the fixer (or allow to configure it in such a way( that it only adds missing @param annotations to docblocks when a docblock exists in the first place?

That is, if a method doesn't have one, just don't touch it?

[localheinz]

Ha, never mind, it doesn't.

[keradus]

Actually not a bad thing. Maybe we shall add (could be configurable) a new docblock when the parameter is not typehinted, so it shall be described in docs ?

A big reasoning for this fixer is to have it be one of automated review tool, that rule is helpful enforcing people to properly document interface.

Reopening to get more feedback from users.

[ossinkine]

IMO docblock should always contain @param tags for all arguments and should contain @return tag if method returns anything. So fixer should add all missing tags and remove unnecessary tags.

[keradus]

pure php5 approach, not treated as valid by many since php7

[SpacePossum]

agreed, it does however annoy me Phpstorm keeps flagging the 'missing tags'.
How about some config options?

[mpaddle]

Would it make sense to create a new fixer for this, to run after PhpdocAddMissingParamAnnotationFixer?

I can imagine changing PhpdocAddMissingParamAnnotationFixer to deal with these cases, but then it would need to be renamed as it would deal with return type annotations as well. Is renaming a possibility?