Php-cs-fixer: [RFC] Remove @param and @return when they don't provide new informations

[michaelcontento]

Description:

I'd like to propose the idea of a "strip down useless PHPDoc"-fixer that:

• Removes @param records when they don't provide additional informations
• Removes @return records when they don't provide additional informations

Before:

<?php

class Example
{
    /**
     * @param \stdClass $obj
     * @return \stdClass
     */
    public function canBeRemoved(\stdClass $obj): \stdClass
    {
    }

    /**
     * @param \stdClass|array $mixed
     * @return \stdClass
     */
    public function canNotBeRemoved($mixed): \stdClass
    {
    }

    /**
     * @param \stdClass $obj
     * @param int|bool $mixed
     * @return \stdClass
     */
    public function firstParamCanBeRemoved(\stdClass $obj, $mixed): \stdClass
    {
    }
}

After:

<?php

class Example
{
    public function canBeRemoved(\stdClass $obj): \stdClass
    {
    }

    /**
     * @param \stdClass|array $mixed
     */
    public function canNotBeRemoved($mixed): \stdClass
    {
    }

    /**
     * @param int|bool $mixed
     */
    public function firstParamCanBeRemoved(\stdClass $obj, $mixed): \stdClass
    {
    }
}

[keradus]

Hi.
This feature was accepted and even discussed how to do it as part of bigger, more generic rule.
Need to find that discussion.
@localheinz , I remember I was discussing it with you and you thumbed this issue as well, do you remember our discussion?

[localheinz]

@keradus

Cannot recall, but I remember countless times re-iterating personal rules for when a method needs a docblock and when it doesn't to former team members, hehe.

In the light of that, a fixer that solves this problem would be a nice addition to the tool belt!

[localheinz]

However, I would suggest to

• remove entire docblocks only when they do not contain any additional information
• not remove parts of a docblock

class Example
{
/**
* @param \stdClass $obj
* @return \stdClass
*/
public function canBeRemoved(\stdClass $obj): \stdClass
{
}

/**
 * @param \stdClass|array $mixed
 * @return \stdClass
 */
public function canNotBeRemoved($mixed): \stdClass
{
}

/**
 * @param \stdClass $obj
 * @param int|bool $mixed
 * @return \stdClass
 */
public function firstParamCanBeRemoved(\stdClass $obj, $mixed): \stdClass
{
}

}
After:

class Example
{
public function canBeRemoved(\stdClass $obj): \stdClass
{
}

/**
 * @param \stdClass|array $mixed
 */
public function canNotBeRemoved($mixed): \stdClass
{
}

/**
 * @param int|bool $mixed
 */
public function firstParamCanBeRemoved(\stdClass $obj, $mixed): \stdClass
{
}

}
```

[keradus]

ok, I will try to find that ticket to have full overview and not creating 2 different specs.

[julienfalque]

I think you are looking for https://github.com/FriendsOfPHP/PHP-CS-Fixer/issues/2464 :)

[mpaddle]

@keradus Is there a spec for this issue? Or is it waiting for a pull request?

[keradus]

The most complete would be already mentioned #2464, i think

[soullivaneuh]

not remove parts of a docblock

This should be configurable IMHO. Some libraries adopt removing useless part while keeping the PHPDoc.

@keradus BTW, is not the way Symfony maintainers are moving?

Another test case:

Before:

class Example
{
    /**
     * @param string $name
     * @param string $email This should be kept because of the custom description.
     */
    public function display(string $name, string $email): void
    {
    }
}

After:

class Example
{
    /**
     * @param string $email This should be kept because of the custom description.
     */
    public function display(string $name, string $email): void
    {
    }
}