feat(DocComment): Avoid misleading message when inheritdoc is missing the curly braces (#2904801)

Author: jonathan1055

coder_sniffer/Drupal/Sniffs/Commenting/DocCommentSniff.php

@@ -139,10 +139,23 @@ public function process(File $phpcsFile, $stackPtr)
                 return;
             }
 
+            // If inheritDoc is found without curly braces it is identified as a T_DOC_COMMENT_TAG not a
+            // T_DOC_COMMENT_STRING. It would be misleading to give the 'Missing short description' error
+            // below, hence we give a more useful message and can fix it automatically.
+            if (stripos($tokens[$short]['content'], '@inheritdoc') === 0) {
+                $error = "{$tokens[$short]['content']} found. Did you mean {{$tokens[$short]['content']}}?";
+                $fix   = $phpcsFile->addFixableError($error, $short, 'InheritDocWithoutBraces');
+                if ($fix === true) {
+                    $phpcsFile->fixer->replaceToken($short, "{{$tokens[$short]['content']}}");
+                }
+
+                return;
+            }
+
             $error = 'Missing short description in doc comment';
             $phpcsFile->addError($error, $stackPtr, 'MissingShort');
             return;
-        }
+        }//end if
 
         if (isset($fileShort) === true) {
             $start = $fileShort;

tests/Drupal/Commenting/DocCommentUnitTest.inc

@@ -121,3 +121,18 @@ function test13() {
 function test14(array $matches, array $sub_key, $to) {
 
 }
+
+/**
+ * {@inheritdoc}
+ */
+function test15_this_inheritdoc_is_correct();
+
+/**
+ * @inheritdoc
+ */
+function test16_lower_case_fail_needs_braces();
+
+/**
+ * @inheritDoc
+ */
+function test17_camel_case_fail_needs_braces();

tests/Drupal/Commenting/DocCommentUnitTest.inc.fixed

@@ -130,3 +130,18 @@ function test13() {
 function test14(array $matches, array $sub_key, $to) {
 
 }
+
+/**
+ * {@inheritdoc}
+ */
+function test15_this_inheritdoc_is_correct();
+
+/**
+ * {@inheritdoc}
+ */
+function test16_lower_case_fail_needs_braces();
+
+/**
+ * {@inheritDoc}
+ */
+function test17_camel_case_fail_needs_braces();

tests/Drupal/Commenting/DocCommentUnitTest.php

@@ -33,6 +33,8 @@ protected function getErrorList(string $testFile): array
                 66  => 1,
                 100 => 4,
                 101 => 1,
+                131 => 1,
+                136 => 1,
             ];
 
         case 'DocCommentUnitTest.1.inc':