From e44cab1f6fda28ac5e5685a7399708bcdd802563 Mon Sep 17 00:00:00 2001
From: Tom Wiesing <tkw01536@gmail.com>
Date: Sat, 4 Oct 2025 10:39:26 +0200
Subject: [PATCH] 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.
---
 .../Sniffs/Commenting/InlineCommentSniff.php  | 16 ++++++--
 .../Commenting/InlineCommentUnitTest.inc      | 38 +++++++++++++++++++
 .../InlineCommentUnitTest.inc.fixed           | 38 +++++++++++++++++++
 .../Commenting/InlineCommentUnitTest.php      | 25 ++++++------
 4 files changed, 102 insertions(+), 15 deletions(-)

diff --git a/coder_sniffer/Drupal/Sniffs/Commenting/InlineCommentSniff.php b/coder_sniffer/Drupal/Sniffs/Commenting/InlineCommentSniff.php
index b5974574..69e74937 100644
--- a/coder_sniffer/Drupal/Sniffs/Commenting/InlineCommentSniff.php
+++ b/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');
                 }
diff --git a/tests/Drupal/Commenting/InlineCommentUnitTest.inc b/tests/Drupal/Commenting/InlineCommentUnitTest.inc
index 5755af9f..fcdf587b 100644
--- a/tests/Drupal/Commenting/InlineCommentUnitTest.inc
+++ b/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;
diff --git a/tests/Drupal/Commenting/InlineCommentUnitTest.inc.fixed b/tests/Drupal/Commenting/InlineCommentUnitTest.inc.fixed
index 16297513..45ff87f5 100644
--- a/tests/Drupal/Commenting/InlineCommentUnitTest.inc.fixed
+++ b/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;
diff --git a/tests/Drupal/Commenting/InlineCommentUnitTest.php b/tests/Drupal/Commenting/InlineCommentUnitTest.php
index 50550fc4..0ad6b153 100644
--- a/tests/Drupal/Commenting/InlineCommentUnitTest.php
+++ b/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()