Add custom ClassCommentSniff

This sniff is the Squiz ClassComment sniff, but only disallowing certain tags in the class docblock

Author: chadicus

Chadicus/Sniffs/Commenting/ClassCommentSniff.php

@@ -0,0 +1,96 @@
+<?php
+/**
+ * Parses and verifies the class doc comment.
+ *
+ * Verifies that :
+ * <ul>
+ *  <li>A class doc comment exists.</li>
+ *  <li>There is exactly one blank line before the class comment.</li>
+ *  <li>There are no blank lines after the class comment.</li>
+ *  <li>Short and long descriptions end with a full stop and start with capital letter.</li>
+ *  <li>There is a blank line between descriptions.</li>
+ *  <li>Disallows throws, return, var and param tags.</li>
+ * </ul>
+ */
+final class Chadicus_Sniffs_Commenting_ClassCommentSniff implements PHP_CodeSniffer_Sniff
+{
+    public $disallowedTags = array('@throws', '@return', '@var', '@param');
+
+    /**
+     * Returns an array of tokens this test wants to listen for.
+     *
+     * @return array
+     */
+    public function register()
+    {
+        return array(T_CLASS, T_INTERFACE);
+    }
+
+    /**
+     * Processes this test, when one of its tokens is encountered.
+     *
+     * @param PHP_CodeSniffer_File $phpcsFile The file being scanned.
+     * @param int                  $stackPtr  The position of the current token
+     *                                        in the stack passed in $tokens.
+     *
+     * @return void
+     */
+    public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
+    {
+        $tokens = $phpcsFile->getTokens();
+        $find   = PHP_CodeSniffer_Tokens::$methodPrefixes;
+        $find[] = T_WHITESPACE;
+
+        $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');
+            return;
+        }
+
+        // Try and determine if this is a file comment instead of a class comment.
+        // We assume that if this is the first comment after the open PHP tag, then
+        // it is most likely a file comment instead of a class comment.
+        if ($tokens[$commentEnd]['code'] === T_DOC_COMMENT_CLOSE_TAG) {
+            $start = ($tokens[$commentEnd]['comment_opener'] - 1);
+        } else {
+            $start = $phpcsFile->findPrevious(T_COMMENT, ($commentEnd - 1), null, true);
+        }
+
+        $prev = $phpcsFile->findPrevious(T_WHITESPACE, $start, null, true);
+        if ($tokens[$prev]['code'] === T_OPEN_TAG) {
+            $prevOpen = $phpcsFile->findPrevious(T_OPEN_TAG, ($prev - 1));
+            if ($prevOpen === false) {
+                // This is a comment directly after the first open tag,
+                // so probably a file comment.
+                $phpcsFile->addError('Missing class doc comment', $stackPtr, 'Missing');
+                return;
+            }
+        }
+
+        if ($tokens[$commentEnd]['code'] === T_COMMENT) {
+            $phpcsFile->addError('You must use "/**" style comments for a class comment', $stackPtr, 'WrongStyle');
+            return;
+        }
+
+        if ($tokens[$commentEnd]['line'] !== ($tokens[$stackPtr]['line'] - 1)) {
+            $error = 'There must be no blank lines after the class comment';
+            $phpcsFile->addError($error, $commentEnd, 'SpacingAfter');
+        }
+
+        $commentStart = $tokens[$commentEnd]['comment_opener'];
+        if ($tokens[$prev]['line'] !== ($tokens[$commentStart]['line'] - 2)) {
+            $error = 'There must be exactly one blank line before the class comment';
+            $phpcsFile->addError($error, $commentStart, 'SpacingBefore');
+        }
+
+        foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
+            if (in_array($tokens[$tag]['content'], $this->disallowedTags)) {
+                $error = '%s tag is not allowed in class comment';
+                $data  = array($tokens[$tag]['content']);
+                $phpcsFile->addWarning($error, $tag, 'TagNotAllowed', $data);
+            }
+        }
+    }
+}

Chadicus/ruleset.xml

@@ -8,7 +8,6 @@
     <rule ref="Generic.CodeAnalysis.UnconditionalIfStatement" />                                                                                 
     <rule ref="Generic.CodeAnalysis.UselessOverridingMethod" />                                                                                  
     <rule ref="Generic.ControlStructures.InlineControlStructure" />                                                                              
-    <rule ref="Squiz.Commenting.ClassComment" />
     <rule ref="Squiz.Commenting.DocCommentAlignment" />                                                                                          
     <rule ref="Squiz.Commenting.FunctionComment" />                                                                                      
     <rule ref="Squiz.Commenting.FunctionCommentThrowTag" />