Squiz and PEAR Class and File sniffs no longer assume the first comme…

…nt in a file is always a file comment (ref #671)
squizlabs · Jan 20, 2016 · dc42502 · dc42502
1 parent e7fd9ad
commit dc42502
Show file tree

Hide file tree

Showing 7 changed files with 89 additions and 56 deletions.
diff --git a/CodeSniffer/Standards/PEAR/Sniffs/Commenting/ClassCommentSniff.php b/CodeSniffer/Standards/PEAR/Sniffs/Commenting/ClassCommentSniff.php
@@ -71,29 +71,9 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
             $phpcsFile->addError('Missing class doc comment', $stackPtr, 'Missing');
             $phpcsFile->recordMetric($stackPtr, 'Class has doc comment', 'no');
             return;
-        } else {
-            $phpcsFile->recordMetric($stackPtr, 'Class has doc comment', 'yes');
         }
 
-        // 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;
-            }
-        }
+        $phpcsFile->recordMetric($stackPtr, 'Class has doc comment', 'yes');
 
         if ($tokens[$commentEnd]['code'] === T_COMMENT) {
             $phpcsFile->addError('You must use "/**" style comments for a class comment', $stackPtr, 'WrongStyle');

diff --git a/CodeSniffer/Standards/PEAR/Sniffs/Commenting/FileCommentSniff.php b/CodeSniffer/Standards/PEAR/Sniffs/Commenting/FileCommentSniff.php
@@ -147,13 +147,47 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
             $phpcsFile->addError('Missing file doc comment', $errorToken, 'Missing');
             $phpcsFile->recordMetric($stackPtr, 'File has doc comment', 'no');
             return ($phpcsFile->numTokens + 1);
-        } else {
-            $phpcsFile->recordMetric($stackPtr, 'File has doc comment', 'yes');
         }
 
-        // Check the PHP Version, which should be in some text before the first tag.
         $commentEnd = $tokens[$commentStart]['comment_closer'];
-        $found      = false;
+
+        $nextToken = $phpcsFile->findNext(
+            T_WHITESPACE,
+            ($commentEnd + 1),
+            null,
+            true
+        );
+
+        $ignore = array(
+                   T_CLASS,
+                   T_INTERFACE,
+                   T_TRAIT,
+                   T_FUNCTION,
+                   T_CLOSURE,
+                   T_PUBLIC,
+                   T_PRIVATE,
+                   T_PROTECTED,
+                   T_FINAL,
+                   T_STATIC,
+                   T_ABSTRACT,
+                   T_CONST,
+                   T_PROPERTY,
+                   T_INCLUDE,
+                   T_INCLUDE_ONCE,
+                   T_REQUIRE,
+                   T_REQUIRE_ONCE,
+                  );
+
+        if (in_array($tokens[$nextToken]['code'], $ignore) === true) {
+            $phpcsFile->addError('Missing file doc comment', $stackPtr, 'Missing');
+            $phpcsFile->recordMetric($stackPtr, 'File has doc comment', 'no');
+            return ($phpcsFile->numTokens + 1);
+        }
+
+        $phpcsFile->recordMetric($stackPtr, 'File has doc comment', 'yes');
+
+        // Check the PHP Version, which should be in some text before the first tag.
+        $found = false;
         for ($i = ($commentStart + 1); $i < $commentEnd; $i++) {
             if ($tokens[$i]['code'] === T_DOC_COMMENT_TAG) {
                 break;

diff --git a/CodeSniffer/Standards/Squiz/Sniffs/Commenting/ClassCommentSniff.php b/CodeSniffer/Standards/Squiz/Sniffs/Commenting/ClassCommentSniff.php
@@ -68,28 +68,11 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
             && $tokens[$commentEnd]['code'] !== T_COMMENT
         ) {
             $phpcsFile->addError('Missing class doc comment', $stackPtr, 'Missing');
+            $phpcsFile->recordMetric($stackPtr, 'Class has doc comment', 'no');
             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;
-            }
-        }
+        $phpcsFile->recordMetric($stackPtr, 'Class has doc comment', 'yes');
 
         if ($tokens[$commentEnd]['code'] === T_COMMENT) {
             $phpcsFile->addError('You must use "/**" style comments for a class comment', $stackPtr, 'WrongStyle');
@@ -102,11 +85,6 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
         }
 
         $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) {
             $error = '%s tag is not allowed in class comment';
             $data  = array($tokens[$tag]['content']);

diff --git a/CodeSniffer/Standards/Squiz/Sniffs/Commenting/FileCommentSniff.php b/CodeSniffer/Standards/Squiz/Sniffs/Commenting/FileCommentSniff.php
@@ -70,14 +70,51 @@ public function process(PHP_CodeSniffer_File $phpcsFile, $stackPtr)
 
         if ($tokens[$commentStart]['code'] === T_COMMENT) {
             $phpcsFile->addError('You must use "/**" style comments for a file comment', $commentStart, 'WrongStyle');
+            $phpcsFile->recordMetric($stackPtr, 'File has doc comment', 'yes');
             return ($phpcsFile->numTokens + 1);
         } else if ($commentStart === false || $tokens[$commentStart]['code'] !== T_DOC_COMMENT_OPEN_TAG) {
             $phpcsFile->addError('Missing file doc comment', $stackPtr, 'Missing');
+            $phpcsFile->recordMetric($stackPtr, 'File has doc comment', 'no');
             return ($phpcsFile->numTokens + 1);
         }
 
         $commentEnd = $tokens[$commentStart]['comment_closer'];
 
+        $nextToken = $phpcsFile->findNext(
+            T_WHITESPACE,
+            ($commentEnd + 1),
+            null,
+            true
+        );
+
+        $ignore = array(
+                   T_CLASS,
+                   T_INTERFACE,
+                   T_TRAIT,
+                   T_FUNCTION,
+                   T_CLOSURE,
+                   T_PUBLIC,
+                   T_PRIVATE,
+                   T_PROTECTED,
+                   T_FINAL,
+                   T_STATIC,
+                   T_ABSTRACT,
+                   T_CONST,
+                   T_PROPERTY,
+                   T_INCLUDE,
+                   T_INCLUDE_ONCE,
+                   T_REQUIRE,
+                   T_REQUIRE_ONCE,
+                  );
+
+        if (in_array($tokens[$nextToken]['code'], $ignore) === true) {
+            $phpcsFile->addError('Missing file doc comment', $stackPtr, 'Missing');
+            $phpcsFile->recordMetric($stackPtr, 'File has doc comment', 'no');
+            return ($phpcsFile->numTokens + 1);
+        }
+
+        $phpcsFile->recordMetric($stackPtr, 'File has doc comment', 'yes');
+
         // No blank line between the open tag and the file comment.
         if ($tokens[$commentStart]['line'] > ($tokens[$stackPtr]['line'] + 1)) {
             $error = 'There must be no blank lines before the file comment';

diff --git a/CodeSniffer/Standards/Squiz/Tests/Commenting/ClassCommentUnitTest.inc b/CodeSniffer/Standards/Squiz/Tests/Commenting/ClassCommentUnitTest.inc
@@ -1,7 +1,7 @@
 <?php
-/** File doc comment */
+/** Class doc comment */
 
-class No_Comment
+class Comment
 {
 
 }//end class

diff --git a/CodeSniffer/Standards/Squiz/Tests/Commenting/ClassCommentUnitTest.php b/CodeSniffer/Standards/Squiz/Tests/Commenting/ClassCommentUnitTest.php
@@ -40,11 +40,10 @@ class Squiz_Tests_Commenting_ClassCommentUnitTest extends AbstractSniffUnitTest
     public function getErrorList()
     {
         return array(
-                4   => 1,
-                15  => 1,
-                31  => 1,
-                39  => 1,
-                54  => 1,
+                2  => 1,
+                15 => 1,
+                31 => 1,
+                54 => 1,
                );
 
     }//end getErrorList()

diff --git a/package.xml b/package.xml
@@ -33,6 +33,11 @@ http://pear.php.net/dtd/package-2.0.xsd">
     -- This change allows ruleset.xml files to be more portable
   - Squiz InlineCommentSniff now allows docblocks on require(_once) and include(_once) statements
     -- Thanks to Gary Jones for the patch
+  - Squiz and PEAR Class and File sniffs no longer assume the first comment in a file is always a file comment
+    -- phpDocumentor assigns the comment to the file only if it is not followed by a structural element
+    -- These sniffs now follow this same rule
+  - Squiz ClassCommentSniff no longer checks for blank lines before class comments
+    -- Removes the error Squiz.Commenting.ClassComment.SpaceBefore
  </notes>
  <contents>
   <dir name="/">