Symfony-coding-standard
Symfony-coding-standard copied to clipboard
djoos
The ruleset force to add PHPDoc blocks for all methods
The Symfony coding strandard documentation states:
Add PHPDoc blocks for all classes, methods, and functions (though you may be asked to remove PHPDoc that do not add value);
For example the inherited methods should not contain any PHPDoc comments, except if we want to add additional details.
I agree. Furthermore, the rules should also sniff useless PHPdoc @param and @return lines like this:
class Test {
/**
* @param string $a
* @param int $b with description.
*
* @return int
*/
public function test(string $a, int $b): int
{
return 42;
}
}
Only $b param notation should be kept because of the custom description.
Maybe including this rule will be enough: https://github.com/slevomat/coding-standard#slevomatcodingstandardtypehintstypehintdeclaration-
PHPdoc @param and @return statements without description are not totally useless. It helps in cases without type declaration (PHP 7). Then I would keep the description as optional. What do you think?
It helps in cases without type declaration (PHP 7)
The rule I suggested removes the phpdoc only if useless. It wont touch anything if the PHP 7 typing is not used.
PHP-CS-Fixer released a new version which configure the Symfony rule for removing PHPDocs when not necessary. At the moment we can't use both PHP-CS-Fixer and this project because the first one remove PHPDocs and the second is requiring them.
you can add the following to your php-cs-fixer config
'no_superfluous_phpdoc_tags' => false,
symfony coding standard still states:
Add PHPDoc blocks for all classes, methods, and functions (though you may be asked to remove PHPDoc that do not add value);
https://symfony.com/doc/current/contributing/code/standards.html#documentation
additionally you should be able to add the following snippet to your phpcs.xml
<rule ref="Symfony.Commenting.FunctionComment.MissingParamTag">
<severity>0</severity>
</rule>
ah ic, you want the parameter requirement to be dropped raqther than the docblock requirement. would make sense with php 7.4+ and property typing i guess...
What I would like is to use the php-cs-fixer @Symfony rule (with the 'no_superfluous_phpdoc_tags' => ['allow_mixed' => true, 'allow_unused_params' => true] config). This way superfluous PHPDocs can be removed because they are redundant with typehinted parameters.
I assume that if I add the MissingParamTag config phpcs won't report error if an parameter is not typehinted and no @param is added in PHPDoc isn't it? IMHO it make sense to remove redundant PHPDocs as it will lighten the code.
though i understand your sentiment, my problem with this is that it's not part of the coding standard / explicitly stated.
so i'd vote for removal of the paramter annotation as that's not explicitly stated as well, and just require a docblock regardless of it's contents, but would say that any additional / custom requirements for parameter annotations should be part of your private sniffs / config.
@djoos what are your thoughts on this?
Please see https://github.com/djoos/Symfony-coding-standard/pull/183 for a start to use Slevomat sniffs instead of homegrown ones and comment there. Pulling in more sniffs would be super easy then.
