How do PEAR class comment and file comment sniffs cooperate?

Question

The PEAR standard has File and Class comment code sniffs and I am uncertain as to how they interact.

The first part of the PEAR class comment check is

$commentEnd = $phpcsFile->findPrevious($find, ($stackPtr - 1), null, true);
if ($tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG
            && $tokens[$commentEnd]['code'] !== T_COMMENT
        ) {
            $phpcsFile->addError('Missing class doc comment', $stackPtr, 'Missing');
            $phpcsFile->recordMetric($stackPtr, 'Class has doc comment', 'no');
            return;
        }

But when presented with the following file it passes as it (presumably) thinks that the file comment is the class comment. Has anyone encountered this before and if so how did you overcome it? Thanks

/** 
 * 
 *  PLATFORM 3 - APACS 29b Recurring Transaction Update Service (RTUS)
 * ==================================================================
 *
 * This class provides the encoding and decoding of recurring transaction update
 * service enquiry and response files that use the APACS 29b protocol as defined
 * in APACS Standard 70 Book 3.
 *
 * @package     Cardstream
 * @subpackage  Pro/System/Classes
 * @copyright   Copyright (c) 2011 - Cardstream Ltd.
 * @author      Nick Turner <nick.turner@cardstream.com>
 * @link        http://www.cardstream.com
 * @version     $Id: p3apacsrtus.php 8195 2016-09-28 13:36:50Z chris.wilson $
 */

class testClass {
}

score 1 · Accepted Answer · answered May 19 '17 at 02:22

The sniff makes the assumption that the comment there is a class comment.

The code you posted does that by starting at the class keyword, then looking for the previous non-whitespace and non-prefix token. In your case, it will find */ which is a T_DOC_COMMENT_CLOSE_TAG token.

The sniff now uses that comment as the class comment.

There is no way to change this behaviour. If you don't use class comments, you probably want to exclude this sniff from your standard. If you use both class and file comments, make sure you also include the PEAR.Commenting.FileComment sniff. Note that the PEAR standard already includes both sniffs so you don't need to do anything if you are using --standard=PEAR.

If you use both sniffs in your standard, the file comment sniff will be reporting that there is no file comment for the file. It too assigns the comment to the class token.

PHPCS has no way to possible know if you missed the class comment or the file comment in this case, so it has to assign the comment to a consistent location and ensure all sniffs are using the same rule.

Once you do have two block comments, the first will be assigned to the file and the second to the class.

How do PEAR class comment and file comment sniffs cooperate?

1 Answers1