Generic/Todo: improve handling of "todo" tags in docblocks

Until now, the sniff would only examine an individual comment token, while when a `@todo` tag is used in a docblock, the "task description" is normally in the next `T_DOC_COMMENT_STRING` token.

This commit fixes this and the sniff will now take docblock `@todo` tags into account.

Includes additional unit tests.

Author: jrfnl

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
 {
@@ -55,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/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()