fix(DocComment): Implement fixer correctly for file comment short description (#3032222)

coder_sniffer/Drupal/Sniffs/Commenting/DocCommentSniff.php

@@ -165,20 +165,25 @@ class DocCommentSniff implements Sniff
             $error = 'Doc comment short description must be on the first line';
             $fix   = $phpcsFile->addFixableError($error, $short, 'SpacingBeforeShort');
             if ($fix === true) {
-                $phpcsFile->fixer->beginChangeset();
-                for ($i = $start; $i < $short; $i++) {
-                    if ($tokens[$i]['line'] === $tokens[$start]['line']) {
-                        continue;
-                    } else if ($tokens[$i]['line'] === $tokens[$short]['line']) {
-                        break;
+                // Move file comment short description to the next line.
+                if (isset($fileShort) === true && $tokens[$short]['line'] === $tokens[$start]['line']) {
+                    $phpcsFile->fixer->addContentBefore($fileShort, "\n *");
+                } else {
+                    $phpcsFile->fixer->beginChangeset();
+                    for ($i = $start; $i < $short; $i++) {
+                        if ($tokens[$i]['line'] === $tokens[$start]['line']) {
+                            continue;
+                        } else if ($tokens[$i]['line'] === $tokens[$short]['line']) {
+                            break;
+                        }
+
+                        $phpcsFile->fixer->replaceToken($i, '');
                     }
 
-                    $phpcsFile->fixer->replaceToken($i, '');
+                    $phpcsFile->fixer->endChangeset();
                 }
-
-                $phpcsFile->fixer->endChangeset();
             }
-        }
+        }//end if
 
         if ($tokens[($short - 1)]['content'] !== ' '
             && strpos($tokens[($short - 1)]['content'], $phpcsFile->eolChar) === false

coder_sniffer/Drupal/Test/Commenting/DocCommentUnitTest.3.inc

+<?php
+
+/**
+ * @file File contains Theming functions and Node definitions.
+ */
+
+require_once DRUPAL_ROOT . '/' . drupal_get_path('module', 'example') . '/example.inc';

coder_sniffer/Drupal/Test/Commenting/DocCommentUnitTest.3.inc.fixed

+<?php
+
+/**
+ * @file
+ * File contains Theming functions and Node definitions.
+ */
+
+require_once DRUPAL_ROOT . '/' . drupal_get_path('module', 'example') . '/example.inc';

coder_sniffer/Drupal/Test/Commenting/DocCommentUnitTest.php

@@ -34,6 +34,9 @@ class DocCommentUnitTest extends CoderSniffUnitTest
                 100 => 4,
                 101 => 1,
             ];
+
+        case 'DocCommentUnitTest.3.inc':
+            return [4 => 1];
         default:
             return [];
         }