Even if I'd love to remove all PHPdocs from all files ... I find it strange to keep some @param and remove others. This is confusing and it will make people submit PRs to add the missing @params in PHPdocs.

Some have added value, some don't and only duplicate information.
What do you suggest then?

What you did is correct, but let me explain the problem I see (using as an example the first change you did):

Original

 /**
  * Adds the stack logger for a connection.
  *
  * @param string     $name
  * @param DebugStack $logger
  */
  public function addLogger($name, DebugStack $logger)

Proposed solution

 /**
  * Adds the stack logger for a connection.
  *
  * @param string $name
  */
  public function addLogger($name, DebugStack $logger)

Best solution

public function addLogger(string $name, DebugStack $logger)

We can't make the best solution to avoid BC issues, but the problem I see with the proposed solution is that people will think we made a mistake and forgot to add the $logger argument in the PHPdocs, because the method has 2 arguments but PHPdoc has only 1.

Yeah, I think partial phpdoc is confusing for users. We should keep an all-or-nothing approach for the parameter list IMO

I see what you mean. Is there any reason to have it such way apart historical reasons? I realize there were not such tools in the past, but today thanks to coding standard tools this is now easy to configure and improve.

It will make code much easier to read for users and easier modify in the future. Moving to Best solution as next step.

Merged Use Case

Similar PRs were merged to php-ai/php-ml lately. Removing over 1700 useless lines.

See especially these cases: https://github.com/php-ai/php-ml/pull/145/files#diff-1359851beb8da185b9d9adae86ab2ff7

people will think we made a mistake and forgot to add the $logger argument in the PHPdocs

This will not happen if fabbot generates the patch, because then, it will become an enforced policy.
So IMHO, we should do this change, but only when fabbot is able to generate the patch.

@TomasVotruba Can you also change the base to 2.7? Thanks.

Are you doing this by hand? Or with a tool? If you are using a tool/regexes/..., can you share it so that merging up to master will be easier?

@fabpot Here is all you asked for: https://www.tomasvotruba.cz/blog/2017/12/17/new-in-symplify-3-doc-block-cleaner-fixer/

Shall I run this rule on 2.7 with current setup then?

@TomasVotruba Can you share you setup? Such PRs are complex to merge as merging it to newest branches is a mess. So, if you can share you setup, I will be able to run it on all branches, limiting the time it takes to merge the change up. Thanks.

@fabpot Sure, I use exactly this setup: https://www.tomasvotruba.cz/blog/2017/12/17/new-in-symplify-3-doc-block-cleaner-fixer/#challenge-your-code

@TomasVotruba I've just tried by it fixes only 15 files.

@fabpot I'm not aware of any major change that could cause this.
Could you share full install script and run command?

And version? Last is 3.1
On which branch?

I've tried on master and v3.2.2, which looks like the last one (from a git clone https://github.com/Symplify/EasyCodingStandard)

@fabpot I meant 3.2, yes.
I'll check it then

I tried it like this:

git clone github.com/symfony/symfony
cd ../symplify # monorepo, with 3.2.3 version (I fixed one variadics bug and just released patch version)
packages/EasyCodingStandard/bin/ecs check ../symfony/src/Symfony --clear-cache --config cleaning-symfony.neon

Where cleaning-symfony.neon

# cleaning-symfony.neon
checkers:
    - Symplify\CodingStandard\Fixer\Commenting\RemoveUselessDocBlockFixer

With this result:

files:

Then with --fix option I'll really get 200 changed files:

I think I forgot to pass the config file. Now it looks much better, but I get this error:

PHP Notice:  Undefined offset: 0 in /Users/fabien/Code/github/Symplify/EasyCodingStandard/vendor/symplify/better-reflection-docblock/src/Tag/TolerantParam.php on line 132

Notice: Undefined offset: 0 in /Users/fabien/Code/github/Symplify/EasyCodingStandard/vendor/symplify/better-reflection-docblock/src/Tag/TolerantParam.php on line 132

In FixerFileProcessor.php line 125:

  Fixing of "src/Symfony/Component/Translation/Dumper/FileDumper.php" file by "Symplify\CodingStandard\Fixer\Commenting\RemoveUselessDocBlockFixer" failed: substr() expects parameter 1 to be string,
  null given in file /Users/fabien/Code/github/Symplify/EasyCodingStandard/vendor/symplify/better-reflection-docblock/src/Tag/TolerantParam.php on line 132

Note that I got the config from your blog post.

Also, I noticed that it removes the blank line between @params and @throws/@return, how can I disable this behavior?

I think I forgot to pass the config file. Now it looks much better, but I get this error:

That's what I fixed. Do you have version 3.2.3?

Note that I got the config from your blog post.

Use the one provided here, just to be sure the main fixer works for you. The other 2 are just space fixers.

Also, I noticed that it removes the blank line between @params and @throws/@return, how can I disable this behavior?

I thinks so. Will create issue for that. It uses ReflectionDocBlock which renders all docblock in one format.

Ok, I forgot to run composer up as the fix was in a dep apparently :)

See #25859 for the current state.