Generic/Todo-Fixme sniffs: improve handling of docblock tags and efficiency fix

src/Standards/Generic/Sniffs/Commenting/FixmeSniff.php

@@ -12,7 +12,6 @@
 
 use PHP_CodeSniffer\Files\File;
 use PHP_CodeSniffer\Sniffs\Sniff;
-use PHP_CodeSniffer\Util\Tokens;
 
 class FixmeSniff implements Sniff
 {
@@ -35,7 +34,12 @@ class FixmeSniff implements Sniff
      */
     public function register()
     {
-        return array_diff(Tokens::$commentTokens, Tokens::$phpcsCommentTokens);
+        return [
+            T_COMMENT,
+            T_DOC_COMMENT,
+            T_DOC_COMMENT_TAG,
+            T_DOC_COMMENT_STRING,
+        ];
 
     }//end register()
 
@@ -51,27 +55,40 @@ public function register()
      */
     public function process(File $phpcsFile, $stackPtr)
     {
-        $tokens = $phpcsFile->getTokens();
-
+        $tokens  = $phpcsFile->getTokens();
         $content = $tokens[$stackPtr]['content'];
         $matches = [];
-        preg_match('/(?:\A|[^\p{L}]+)fixme([^\p{L}]+(.*)|\Z)/ui', $content, $matches);
-        if (empty($matches) === false) {
-            // Clear whitespace and some common characters not required at
-            // the end of a fixme message to make the error more informative.
-            $type         = 'CommentFound';
-            $fixmeMessage = trim($matches[1]);
-            $fixmeMessage = trim($fixmeMessage, '-:[](). ');
-            $error        = 'Comment refers to a FIXME task';
-            $data         = [$fixmeMessage];
-            if ($fixmeMessage !== '') {
-                $type   = 'TaskFound';
-                $error .= ' "%s"';
+
+        if (preg_match('/(?:\A|[^\p{L}]+)fixme([^\p{L}]+(.*)|\Z)/ui', $content, $matches) !== 1) {
+            return;
+        }
+
+        $fixmeMessage = trim($matches[1]);
+        // Clear whitespace and some common characters not required at
+        // the end of a to-do message to make the warning more informative.
+        $fixmeMessage = trim($fixmeMessage, '-:[](). ');
+
+        if ($tokens[$stackPtr]['code'] === T_DOC_COMMENT_TAG
+            && $fixmeMessage === ''
+        ) {
+            $nextNonEmpty = $phpcsFile->findNext(T_DOC_COMMENT_WHITESPACE, ($stackPtr + 1), null, true);
+            if ($nextNonEmpty !== false
+                && $tokens[$nextNonEmpty]['code'] === T_DOC_COMMENT_STRING
+            ) {
+                $fixmeMessage = trim($tokens[$nextNonEmpty]['content'], '-:[](). ');
             }
+        }
 
-            $phpcsFile->addError($error, $stackPtr, $type, $data);
+        $error = 'Comment refers to a FIXME task';
+        $type  = 'CommentFound';
+        $data  = [$fixmeMessage];
+        if ($fixmeMessage !== '') {
+            $error .= ' "%s"';
+            $type   = 'TaskFound';
         }
 
+        $phpcsFile->addError($error, $stackPtr, $type, $data);
+
     }//end process()
 
 

src/Standards/Generic/Sniffs/Commenting/TodoSniff.php

@@ -11,7 +11,6 @@
 
 use PHP_CodeSniffer\Files\File;
 use PHP_CodeSniffer\Sniffs\Sniff;
-use PHP_CodeSniffer\Util\Tokens;
 
 class TodoSniff implements Sniff
 {
@@ -34,7 +33,12 @@ class TodoSniff implements Sniff
      */
     public function register()
     {
-        return array_diff(Tokens::$commentTokens, Tokens::$phpcsCommentTokens);
+        return [
+            T_COMMENT,
+            T_DOC_COMMENT,
+            T_DOC_COMMENT_TAG,
+            T_DOC_COMMENT_STRING,
+        ];
 
     }//end register()
 
@@ -50,27 +54,40 @@ public function register()
      */
     public function process(File $phpcsFile, $stackPtr)
     {
-        $tokens = $phpcsFile->getTokens();
-
+        $tokens  = $phpcsFile->getTokens();
         $content = $tokens[$stackPtr]['content'];
         $matches = [];
-        preg_match('/(?:\A|[^\p{L}]+)todo([^\p{L}]+(.*)|\Z)/ui', $content, $matches);
-        if (empty($matches) === false) {
-            // Clear whitespace and some common characters not required at
-            // the end of a to-do message to make the warning more informative.
-            $type        = 'CommentFound';
-            $todoMessage = trim($matches[1]);
-            $todoMessage = trim($todoMessage, '-:[](). ');
-            $error       = 'Comment refers to a TODO task';
-            $data        = [$todoMessage];
-            if ($todoMessage !== '') {
-                $type   = 'TaskFound';
-                $error .= ' "%s"';
+
+        if (preg_match('/(?:\A|[^\p{L}]+)todo([^\p{L}]+(.*)|\Z)/ui', $content, $matches) !== 1) {
+            return;
+        }
+
+        $todoMessage = trim($matches[1]);
+        // Clear whitespace and some common characters not required at
+        // the end of a to-do message to make the warning more informative.
+        $todoMessage = trim($todoMessage, '-:[](). ');
+
+        if ($tokens[$stackPtr]['code'] === T_DOC_COMMENT_TAG
+            && $todoMessage === ''
+        ) {
+            $nextNonEmpty = $phpcsFile->findNext(T_DOC_COMMENT_WHITESPACE, ($stackPtr + 1), null, true);
+            if ($nextNonEmpty !== false
+                && $tokens[$nextNonEmpty]['code'] === T_DOC_COMMENT_STRING
+            ) {
+                $todoMessage = trim($tokens[$nextNonEmpty]['content'], '-:[](). ');
             }
+        }
 
-            $phpcsFile->addWarning($error, $stackPtr, $type, $data);
+        $error = 'Comment refers to a TODO task';
+        $type  = 'CommentFound';
+        $data  = [$todoMessage];
+        if ($todoMessage !== '') {
+            $error .= ' "%s"';
+            $type   = 'TaskFound';
         }
 
+        $phpcsFile->addWarning($error, $stackPtr, $type, $data);
+
     }//end process()
 
 

src/Standards/Generic/Tests/Commenting/FixmeUnitTest.inc

@@ -21,3 +21,17 @@ Debug::bam('test');
 //FIXME.
 //éfixme
 //fixmeé
+
+/**
+ * While there is no official "fix me" tag, only `@todo`, let's support a tag for the purpose of this sniff anyway.
+ *
+ * @fixme This message should be picked up.
+ * @fixme: This message should be picked up too.
+ * @fixme - here is a message
+ *
+ * The below should not show a message as there is no description associated with the tag.
+ * @fixme
+ * @anothertag
+ *
+ * @param string $something FIXME: add description
+ */

src/Standards/Generic/Tests/Commenting/FixmeUnitTest.js

@@ -21,3 +21,17 @@ alert('test');
 //FIXME.
 //éfixme
 //fixmeé
+
+/**
+ * While there is no official "fix me" tag, only `@todo`, let's support a tag for the purpose of this sniff anyway.
+ *
+ * @fixme This message should be picked up.
+ * @fixme: This message should be picked up too.
+ * @fixme - here is a message
+ *
+ * The below should not show a message as there is no description associated with the tag.
+ * @fixme
+ * @anothertag
+ *
+ * @param string $something FIXME: add description
+ */

src/Standards/Generic/Tests/Commenting/FixmeUnitTest.php

@@ -37,6 +37,11 @@ public function getErrorList($testFile='FixmeUnitTest.inc')
             16 => 1,
             18 => 1,
             21 => 1,
+            28 => 1,
+            29 => 1,
+            30 => 1,
+            33 => 1,
+            36 => 1,
         ];
 
     }//end getErrorList()

src/Standards/Generic/Tests/Commenting/TodoUnitTest.inc

@@ -21,3 +21,15 @@ Debug::bam('test');
 //TODO.
 //étodo
 //todoé
+
+/**
+ * @todo This message should be picked up.
+ * @todo: This message should be picked up too.
+ * @todo - here is a message
+ *
+ * The below should not show a message as there is no description associated with the tag.
+ * @todo
+ * @anothertag
+ *
+ * @param string $something TODO: add description
+ */

src/Standards/Generic/Tests/Commenting/TodoUnitTest.js

@@ -21,3 +21,15 @@ alert('test');
 //TODO.
 //étodo
 //todoé
+
+/**
+ * @todo This message should be picked up.
+ * @todo: This message should be picked up too.
+ * @todo - here is a message
+ *
+ * The below should not show a message as there is no description associated with the tag.
+ * @todo
+ * @anothertag
+ *
+ * @param string $something TODO: add description
+ */

src/Standards/Generic/Tests/Commenting/TodoUnitTest.php

@@ -53,6 +53,11 @@ public function getWarningList($testFile='TodoUnitTest.inc')
             16 => 1,
             18 => 1,
             21 => 1,
+            26 => 1,
+            27 => 1,
+            28 => 1,
+            31 => 1,
+            34 => 1,
         ];
 
     }//end getWarningList()