PHP_CodeSniffer: DocCommentSniff reporting single-line block comments as error

There are 2 way how you can write a block comment:

class Something
{
    /**
     * Description.
     *
     * @var ClassName
     */
    protected $somethingMultiLine;

    /** @var ClassName Description */
    protected $somethingElse;

}

Same goes for method DocBlocks and DocBlocks for individual variables in the code.

However the DocCommentSniff reports 1st line in following code as error:

/** @var NodeElement $content_box_title */
$content_box_title = array_shift($content_box_titles);

Error text: The open comment tag must be the only content on the line Error code: ContentAfterOpen

Reference: http://www.phpdoc.org/docs/latest/references/phpdoc/tags/var.html

About this issue

Original URL
State: open
Created 10 years ago
Reactions: 21
Comments: 27 (20 by maintainers)

Most upvoted comments

That’s perfectly ok. It’s that specific check that concerns me, not others. I’m just worried that if somebody using @var (and I bet somebody is using them) will hit this new check and need to disable that specific error manually as well.

👍 Just want to point out that single line DocBlocks are part of the proposed PSR-5 with @type (and @var).

Mairu on Sep 25, 2014

@bkdotcom You can do something like this for now.

glen-84 on May 12, 2020

ping

aik099 on Jun 20, 2016

@glen-84 thanks… I also had to exclude Squiz.Commenting.BlockComment.WrongStart and Squiz.Commenting.InlineComment.DocBlock

I believe the only relevant sniffs left in play are the PSR12 sniffs

bkdotcom on May 12, 2020

So, what is the argument for not including this in the generic checks? Given that PHPDoc itself is a mature standard, I don’t see any reason to wait for PSR-5, if it’s even completed; it will just refine the existing PHPDoc standard.

miken32 on May 24, 2017