Coding-standard: TypeHintDeclarationSniff removing Doctrine annotations

[enumag]

Several times now I got this:

Method ........ does not need documentation comment.                                                                                          
(SlevomatCodingStandard\Sniffs\TypeHints\TypeHintDeclarationSniff)   

And the entire docblock with the annotations was removed.

I know I can set some annotations to not be removed like this with usefulAnnotations but my application uses a lot of Doctrine annotations (Doctrine entities, Symfony validators, Arachne/Verifier rules and so on) so the list would be really really long and I could easily forget something. Is there a better way to prevent removal of Doctrine annotations?

[kukulich]

See https://github.com/slevomat/coding-standard/pull/107#issuecomment-281466747

[enumag]

@kukulich Prefix is useless for me. My annotations mostly do not use any prefix. For example these annotations are removed now:

<?php declare(strict_types = 1);

namespace App\Web\Controller\Dashboard;

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;

class IndexController
{
    /**
     * @Route("/")
     * @Template()
     */
    public function __invoke()
    {
        // ...
    }
}

[kukulich]

I will close this ticket because there's no bug in the sniff.

You can:

1. Disable the whole sniff
2. Disable only UselessDocComment
3. Change the way you write annotations and use prefixes - eg. use @ORM\GeneratedValue() for Doctrine annotations.
4. Add all annotations to usefulAnnotations

[enumag]

Disable only UselessDocComment

This seems like the way to go. I didn't know it was possible. I'm not quite sure how to do it with EasyCodingStandard though. Any idea?

cc @TomasVotruba

[kukulich]

It's easy with standard PHPCS configuration: https://github.com/Roave/BetterReflection/blob/master/phpcs.xml#L96

[TomasVotruba]

@enumag That is not possible. Only class identifiers are supported.

[TomasVotruba]

Btw, this was no-go for many people I showed Slevomat coding standard to.
Common Symfony and Doctrine annotations should be ignore by default.

[enumag]

@kukulich @TomasVotruba I don't mind disabling UselessDocComment altogether. We need to solve this somehow though. As it is I would be forced to disable the sniff completely.

[ondrejmirtes]

Only class identifiers are supported.

This is unfortunate because Slevomat CS supports very granular settings based on sniff error codes, almost all sniffs have several of them.

[TomasVotruba]

I think this sniff is doing too much.

I should be in standalone sniff, like:
https://github.com/FriendsOfPHP/PHP-CS-Fixer/blob/2.7/src/Fixer/Phpdoc/GeneralPhpdocAnnotationRemoveFixer.php

[enumag]

@TomasVotruba I agree the sniffs should be more separate than they are now but having ECS to be completely unable to configure sniffs like this is really not good. Let's talk tomorrow about how to add the support.

[TomasVotruba]

Kk

[enumag]

@kukulich @TomasVotruba I have disabled UselessDocComment using the new configuration in ECS. The result is that when I run vendor/bin/ecs check src the errors are not there - good. But then when I run vendor/bin/ecs check src --fix the annotations are still removed. It seems it only suppresses the errors in the output but it does not prevent the sniff from breaking my code. :disappointed:

[enumag]

It looks like these lines are only checking if the sniff is suppressed by annotation but ignore that it can be suppressed by configuration.

Any idea how to fix that? I can send a PR if you tell me how to do it.

[kukulich]

@enumag It's probably bug in ECS.

[enumag]

@kukulich I'll try to run code sniffer normally to confirm or disprove your claim.

[enumag]

... any idea how to configure phpcs to use this sniff and preferably no other sniffs? It's more complicated than I expected. I never used phpcs on its own so I'm not sure how to configure it to do this.

[enumag]

Ok I can run it now with this configuration:

<?xml version="1.0"?>
<ruleset name="AcmeProject">
    <config name="installed_paths" value="../../slevomat/coding-standard"/>
    <rule ref="SlevomatCodingStandard.TypeHints.TypeHintDeclaration"/>
</ruleset>

vendor/bin/phpcbf --standard=ruleset.xml --extensions=php --tab-width=4 -sp src

I'm just not sure hot to correctly disable UselessDocComment here.

[VasekPurchart]

See for example https://github.com/slevomat/coding-standard/blob/master/build/phpcs.xml#L18.

[enumag]

Is seems that this configuration fixes the problem. So there is probably indeed something wrong in ECS.

<?xml version="1.0"?>
<ruleset name="AcmeProject">
    <config name="installed_paths" value="../../slevomat/coding-standard"/>
    <rule ref="SlevomatCodingStandard.TypeHints.TypeHintDeclaration">
        <exclude name="SlevomatCodingStandard.TypeHints.TypeHintDeclaration.UselessDocComment"/>
    </rule>
</ruleset>

[github-actions[bot]]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.