Php_codesniffer: PSR12.Traits.UseDeclaration does not allow comments above a USE declaration

[dereuromark]

False-positive on reporting:

class Repeater implements RepeaterInterface
{
    /**
     * This is some text
     *
     * We need the configuration ... foo bar.
     */
    use BundleConfigResolverAwareTrait;

wrongly reports

FOUND 1 ERROR AFFECTING 1 LINE
----------------------------------------------------------------------
 27 | ERROR | The first trait import statement must be declared on
    |       | the line after the class opening brace

moved from https://github.com/squizlabs/PHP_CodeSniffer/issues/2624

[gsherwood]

This is an annoying one as PSR-12 states:

The use keyword used inside the classes to implement traits MUST be declared on the next line after the opening brace.

It's very clear that the use keyword itself must be on the next line, but this leaves absolutely no room for a comment.

I'd normally attempt to ask for clarification on the mailing list but this hasn't done me any good any other time I've tried with PSR-12, so I think the best thing to do is go against the exact wording of the standard and just ignore the comment.

If the comment didn't exist, would the use keyword be on the line after class opening brace? If so, then it's fine. If there is a blank line before or after the comment, then the answer is no, and the error should be shown.

So this would generate an error:

class Repeater implements RepeaterInterface
{

    /**
     * Comment
     */
    use BundleConfigResolverAwareTrait;
}

And so would this:

class Repeater implements RepeaterInterface
{
    /**
     * Comment
     */

    use BundleConfigResolverAwareTrait;
}

Any thoughts?

[dereuromark]

Jep, the comment is optional.
The main issue is here about functional code, and e.g. class constants and class props coming after the use statements.

So I agree with you here, non functional doc block must not count into it - and as long as no extra newlines are in between all is well.

[gsherwood]

I've pushed a change to ignore comments now. Thanks for reporting this.

[AlecWeekes]

This issue continues to be a problem for subsequent comments.

Example A:

class ClassName
{
    /**
     * DocBlockContent
     */
    use FirstTrait;
    use SecondTrait;
    use ThirdTrait;
}

Example B:

class ClassName
{
    /**
     * DocBlockContent
     */
    use FirstTrait;

    /**
     * DocBlockContent
     */
    use SecondTrait;

    /**
     * DocBlockContent
     */
    use ThirdTrait;
}

Example A passes the tests, while Example B does not. Being unable to properly document your Traits isn't helpful at all.