fix(DocComment): Improve fixer for short comments not ending in a full stop (#3184314)

coder_sniffer/Drupal/Sniffs/Commenting/DocCommentSniff.php

@@ -233,6 +233,7 @@ class DocCommentSniff implements Sniff
         }
 
         $lastChar = substr($shortContent, -1);
+        // Allow these characters as valid line-ends not requiring to be fixed.
         if (in_array($lastChar, ['.', '!', '?', ')']) === false
             // Allow both variants of inheritdoc comments.
             && $shortContent !== '{@inheritdoc}'
@@ -242,9 +243,17 @@ class DocCommentSniff implements Sniff
             && $shortContent !== basename($phpcsFile->getFilename())
         ) {
             $error = 'Doc comment short description must end with a full stop';
-            $fix   = $phpcsFile->addFixableError($error, $shortEnd, 'ShortFullStop');
-            if ($fix === true) {
-                $phpcsFile->fixer->addContent($shortEnd, '.');
+            // If the last character is alphanumeric and the content is all on one line then fix it.
+            if (preg_match('/[a-zA-Z0-9]/', $lastChar) === 1
+                && $tokens[$short]['line'] === $tokens[$shortEnd]['line']
+            ) {
+                $fix = $phpcsFile->addFixableError($error, $shortEnd, 'ShortFullStop');
+                if ($fix === true) {
+                    $phpcsFile->fixer->addContent($shortEnd, '.');
+                }
+            } else {
+                // The correct fix is not obvious, so report an error and leave for manual correction.
+                $phpcsFile->addError($error, $shortEnd, 'ShortFullStop');
             }
         }
 

tests/Drupal/Commenting/DocCommentUnitTest.1.inc

@@ -7,3 +7,36 @@
  * A comprehensive guide with examples is available at:
  * @link http://example.com Test link @endlink.
  */
+
+/**
+ * Short comment with acceptable ending punctuation that does not need fixing!
+ */
+
+/**
+ * It is an unlikely comment, but question marks are acceptable, and why not?
+ */
+
+/**
+ * Brackets are also an allowed ending with no warning()
+ */
+
+/**
+ * This is a short comment with no full stop that can be fixed automatically
+ */
+
+/**
+ * A comment ending in digits is fixable, but the number of these in Core is 0
+ */
+
+/**
+ * No full stop that should not be fixed, just give the error message;
+ */
+
+/**
+ * This is an error that should not be fixed either-
+ */
+
+/**
+ * This is the first doc comment but it spans on to a second line and adding a
+ * full-stop will not fix the short comment so just report the error
+ */

tests/Drupal/Commenting/DocCommentUnitTest.1.inc.fixed

@@ -7,3 +7,36 @@
  * A comprehensive guide with examples is available at:
  * @link http://example.com Test link @endlink.
  */
+
+/**
+ * Short comment with acceptable ending punctuation that does not need fixing!
+ */
+
+/**
+ * It is an unlikely comment, but question marks are acceptable, and why not?
+ */
+
+/**
+ * Brackets are also an allowed ending with no warning()
+ */
+
+/**
+ * This is a short comment with no full stop that can be fixed automatically.
+ */
+
+/**
+ * A comment ending in digits is fixable, but the number of these in Core is 0.
+ */
+
+/**
+ * No full stop that should not be fixed, just give the error message;
+ */
+
+/**
+ * This is an error that should not be fixed either-
+ */
+
+/**
+ * This is the first doc comment but it spans on to a second line and adding a
+ * full-stop will not fix the short comment so just report the error
+ */

tests/Drupal/Commenting/DocCommentUnitTest.php

@@ -35,11 +35,20 @@ class DocCommentUnitTest extends CoderSniffUnitTest
                 101 => 1,
             ];
 
+        case 'DocCommentUnitTest.1.inc':
+            return [
+                24 => 1,
+                28 => 1,
+                32 => 1,
+                36 => 1,
+                41 => 2,
+            ];
+
         case 'DocCommentUnitTest.3.inc':
             return [4 => 1];
         default:
             return [];
-        }
+        }//end switch
 
     }//end getErrorList()