fix(InlineComment): Allow custom docblock tags (#3367776)

Previously, the InlineComment sniff flagged inline DocBlocks as long as
they did not contain a '@var' tag. As noted in #3367776, it is desirable
to also allow other (possibly custom) docblock tags.

This commit updates InlineCommentSniff.php to allow any inline doc
blocks that start with a doc comment tag, e.g. /** @var */. Any trailing
content is allowed, however the docblock tag must be first.

This commit also adds appropriate test cases to InlineCommentSniff.php.

Author: tkw1536

coder_sniffer/Drupal/Sniffs/Commenting/InlineCommentSniff.php

@@ -111,10 +111,18 @@ public function process(File $phpcsFile, $stackPtr)
             }
 
             if ($tokens[$stackPtr]['content'] === '/**') {
-                // The only exception to inline doc blocks is the /** @var */
-                // declaration. Allow that in any form.
-                $varTag = $phpcsFile->findNext([T_DOC_COMMENT_TAG], ($stackPtr + 1), $tokens[$stackPtr]['comment_closer'], false, '@var');
-                if ($varTag === false) {
+                // The only exception are inline doc blocks that start with a doc comment tag, e.g. /** @var */.
+                // Any trailing content after the comment tag is fine.
+                $anyTag = $phpcsFile->findNext([T_DOC_COMMENT_TAG], ($stackPtr + 1), $tokens[$stackPtr]['comment_closer'], false);
+
+                // Ensure that there is nothing but stars and whitespace before the tag starts.
+                // In particular, preceding text is not allowed.
+                $beforeTag = false;
+                if ($anyTag !== false) {
+                    $beforeTag = $phpcsFile->findNext([T_DOC_COMMENT_STAR, T_DOC_COMMENT_WHITESPACE], ($stackPtr + 1), $anyTag, true);
+                }
+
+                if ($anyTag === false || $beforeTag !== false) {
                     $error = 'Inline doc block comments are not allowed; use "/* Comment */" or "// Comment" instead';
                     $phpcsFile->addError($error, $stackPtr, 'DocBlock');
                 }

tests/Drupal/Commenting/InlineCommentUnitTest.inc

@@ -117,6 +117,44 @@ function test2() {
   return $x;
 }
 
+/**
+ * Check more inline doc block cases.
+ */
+function test3() {
+  /** I am not allowed. */
+  something();
+
+  /**
+    * I am also not allowed.
+    * Even though I go on multiple lines.
+    */
+  something();
+
+  /** @some-unknown-tag I am allowed. */
+  something();
+
+  /**
+   *
+   * @some-tag-on-the-third-line */
+  something();
+
+  /**
+   * @some-tag-here
+   *
+   * Additonal text after is fine.
+   */
+  something();
+
+  /**
+   * There is some text here before the doc tag.
+   *
+   * This should not be allowed.
+   *
+   * @some-other-tag
+   */
+  something();
+}
+
 // Allow all the cspell comment variants.
 // cspell:ignore bananarama
 $x = 1;

tests/Drupal/Commenting/InlineCommentUnitTest.inc.fixed

@@ -116,6 +116,44 @@ function test2() {
   return $x;
 }
 
+/**
+ * Check more inline doc block cases.
+ */
+function test3() {
+  /** I am not allowed. */
+  something();
+
+  /**
+    * I am also not allowed.
+    * Even though I go on multiple lines.
+    */
+  something();
+
+  /** @some-unknown-tag I am allowed. */
+  something();
+
+  /**
+   *
+   * @some-tag-on-the-third-line */
+  something();
+
+  /**
+   * @some-tag-here
+   *
+   * Additonal text after is fine.
+   */
+  something();
+
+  /**
+   * There is some text here before the doc tag.
+   *
+   * This should not be allowed.
+   *
+   * @some-other-tag
+   */
+  something();
+}
+
 // Allow all the cspell comment variants.
 // cspell:ignore bananarama
 $x = 1;

tests/Drupal/Commenting/InlineCommentUnitTest.php

@@ -21,17 +21,20 @@ class InlineCommentUnitTest extends CoderSniffUnitTest
     protected function getErrorList(string $testFile): array
     {
         return [
-            8  => 1,
-            10 => 1,
-            13 => 1,
-            15 => 1,
-            20 => 1,
-            24 => 1,
-            44 => 1,
-            47 => 1,
-            62 => 1,
-            84 => 1,
-            86 => 1,
+            8   => 1,
+            10  => 1,
+            13  => 1,
+            15  => 1,
+            20  => 1,
+            24  => 1,
+            44  => 1,
+            47  => 1,
+            62  => 1,
+            84  => 1,
+            86  => 1,
+            124 => 1,
+            127 => 1,
+            148 => 1,
         ];
 
     }//end getErrorList()