From 30d18970455ea356cc24212091969e078a3b154f Mon Sep 17 00:00:00 2001
From: Dan Wallis <mrdanwallis@gmail.com>
Date: Fri, 3 Feb 2023 17:54:31 +0000
Subject: [PATCH 1/7] Allow auto-fixing Generic.Commenting.DocComment

---
 .../Sniffs/Commenting/DocCommentSniff.php     | 225 ++++++++++++++++--
 .../Tests/Commenting/DocCommentUnitTest.inc   |  29 ++-
 .../Commenting/DocCommentUnitTest.inc.fixed   |  69 ++++--
 .../Tests/Commenting/DocCommentUnitTest.php   |  52 ++--
 4 files changed, 311 insertions(+), 64 deletions(-)

diff --git a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
index 545319be5e..daef9be1f7 100644
--- a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
+++ b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
@@ -71,9 +71,31 @@ public function process(File $phpcsFile, $stackPtr)
         if ($short === false) {
             // No content at all.
             $error = 'Doc comment is empty';
-            $phpcsFile->addError($error, $stackPtr, 'Empty');
+            $fix   = $phpcsFile->addFixableError($error, $stackPtr, 'Empty');
+
+            if ($fix === true) {
+                $phpcsFile->fixer->beginChangeset();
+                for ($i = $commentStart; $i <= $commentEnd; $i++) {
+                    $phpcsFile->fixer->replaceToken($i, '');
+                }
+
+                $tokenBefore = ($tokens[($commentStart - 1)] ?? null);
+                $tokenAfter  = ($tokens[($commentEnd + 1)] ?? null);
+                if ($tokenBefore !== null
+                    && $tokenBefore['code'] === T_WHITESPACE
+                    && $tokenBefore['content'] === $phpcsFile->eolChar
+                    && $tokenAfter !== null
+                    && $tokenAfter['code'] === T_WHITESPACE
+                    && $tokenAfter['content'] === $phpcsFile->eolChar
+                ) {
+                    $phpcsFile->fixer->replaceToken(($commentStart - 1), '');
+                }
+
+                $phpcsFile->fixer->endChangeset();
+            }
+
             return;
-        }
+        }//end if
 
         // The first line of the comment should just be the /** code.
         if ($tokens[$short]['line'] === $tokens[$stackPtr]['line']) {
@@ -157,7 +179,22 @@ public function process(File $phpcsFile, $stackPtr)
 
             if (preg_match('/^\p{Ll}/u', $shortContent) === 1) {
                 $error = 'Doc comment short description must start with a capital letter';
-                $phpcsFile->addError($error, $short, 'ShortNotCapital');
+
+                $firstCharacter      = mb_substr($shortContent, 0, 1);
+                $firstCharacterUpper = mb_strtoupper($firstCharacter);
+                $fix = false;
+
+                if ($firstCharacter !== $firstCharacterUpper) {
+                    $fix = $phpcsFile->addFixableError($error, $short, 'ShortNotCapital');
+                } else {
+                    $phpcsFile->addError($error, $short, 'ShortNotCapital');
+                }
+
+                if ($fix === true) {
+                    $phpcsFile->fixer->beginChangeset();
+                    $phpcsFile->fixer->replaceToken($short, $firstCharacterUpper.mb_substr($tokens[$short]['content'], 1));
+                    $phpcsFile->fixer->endChangeset();
+                }
             }
 
             $long = $phpcsFile->findNext($empty, ($shortEnd + 1), ($commentEnd - 1), true);
@@ -183,7 +220,22 @@ public function process(File $phpcsFile, $stackPtr)
 
                 if (preg_match('/^\p{Ll}/u', $tokens[$long]['content']) === 1) {
                     $error = 'Doc comment long description must start with a capital letter';
-                    $phpcsFile->addError($error, $long, 'LongNotCapital');
+
+                    $firstCharacter      = mb_substr($tokens[$long]['content'][0], 0, 1);
+                    $firstCharacterUpper = mb_strtoupper($firstCharacter);
+                    $fix = false;
+
+                    if ($firstCharacter !== $firstCharacterUpper) {
+                        $fix = $phpcsFile->addFixableError($error, $long, 'LongNotCapital');
+                    } else {
+                        $phpcsFile->addError($error, $long, 'LongNotCapital');
+                    }
+
+                    if ($fix === true) {
+                        $phpcsFile->fixer->beginChangeset();
+                        $phpcsFile->fixer->replaceToken($long, $firstCharacterUpper.mb_substr($tokens[$long]['content'], 1));
+                        $phpcsFile->fixer->endChangeset();
+                    }
                 }
             }//end if
         }//end if
@@ -193,6 +245,8 @@ public function process(File $phpcsFile, $stackPtr)
             return;
         }
 
+        $indent = str_repeat(' ', $tokens[$stackPtr]['column']);
+
         $firstTag = $tokens[$commentStart]['comment_tags'][0];
         $prev     = $phpcsFile->findPrevious($empty, ($firstTag - 1), $stackPtr, true);
         if ($tokens[$firstTag]['line'] !== ($tokens[$prev]['line'] + 2)
@@ -210,7 +264,6 @@ public function process(File $phpcsFile, $stackPtr)
                     $phpcsFile->fixer->replaceToken($i, '');
                 }
 
-                $indent = str_repeat(' ', $tokens[$stackPtr]['column']);
                 $phpcsFile->fixer->addContent($prev, $phpcsFile->eolChar.$indent.'*'.$phpcsFile->eolChar);
                 $phpcsFile->fixer->endChangeset();
             }
@@ -222,6 +275,7 @@ public function process(File $phpcsFile, $stackPtr)
         $tagGroups    = [];
         $groupid      = 0;
         $paramGroupid = null;
+        $firstTagAfterParams = null;
         foreach ($tokens[$commentStart]['comment_tags'] as $pos => $tag) {
             if ($pos > 0) {
                 $prev = $phpcsFile->findPrevious(
@@ -244,28 +298,93 @@ public function process(File $phpcsFile, $stackPtr)
                     && $paramGroupid !== $groupid
                 ) {
                     $error = 'Parameter tags must be grouped together in a doc comment';
-                    $phpcsFile->addError($error, $tag, 'ParamGroup');
-                }
+                    $fix   = $phpcsFile->addFixableError($error, $tag, 'ParamGroup');
+
+                    if ($fix === true) {
+                        $phpcsFile->fixer->beginChangeset();
+
+                        $thisTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $tag, $commentStart, false, $phpcsFile->eolChar));
+
+                        if (isset($tokens[$stackPtr]['comment_tags'][($pos + 1)]) === true) {
+                            $nextTag          = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($tag + 1), $commentEnd);
+                            $nextTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $nextTag, $commentStart, false, $phpcsFile->eolChar));
+                        } else {
+                            $nextTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $commentEnd, $commentStart, false, $phpcsFile->eolChar));
+                        }
+
+                        $thisTagContent = '';
+                        for ($i = $thisTagLineStart; $i < $nextTagLineStart; $i++) {
+                            if ($tokens[($i - 1)]['content'] === $phpcsFile->eolChar
+                                && $tokens[$i]['content'] === $indent
+                                && $tokens[($i + 1)]['content'] === '*'
+                                && $tokens[($i + 2)]['content'] === $phpcsFile->eolChar
+                            ) {
+                                break;
+                            }
+
+                            $thisTagContent .= $tokens[$i]['content'];
+                            $phpcsFile->fixer->replaceToken($i, '');
+                        }
+
+                        $insertionPointer = $phpcsFile->findPrevious(T_DOC_COMMENT_TAG, ($tag - 1), $commentStart, false, '@param');
+
+                        while ($tokens[($insertionPointer - 1)]['content'] !== $phpcsFile->eolChar
+                            || $tokens[$insertionPointer]['content'] !== $indent
+                            || $tokens[($insertionPointer + 1)]['content'] !== '*'
+                            || $tokens[($insertionPointer + 2)]['content'] !== $phpcsFile->eolChar
+                        ) {
+                            $insertionPointer++;
+                        }
+
+                        $phpcsFile->fixer->addContentBefore($insertionPointer, $thisTagContent);
+
+                        $phpcsFile->fixer->endChangeset();
+                    }//end if
+                }//end if
 
                 if ($paramGroupid === null) {
                     $paramGroupid = $groupid;
                 }
+            } else if ($paramGroupid !== null && $firstTagAfterParams === null) {
+                $firstTagAfterParams = $tag;
             }//end if
 
             $tagGroups[$groupid][] = $tag;
         }//end foreach
 
         foreach ($tagGroups as $groupid => $group) {
-            $maxLength = 0;
-            $paddings  = [];
+            $maxLength           = 0;
+            $paddings            = [];
+            $canFixNonParamGroup = true;
             foreach ($group as $pos => $tag) {
                 if ($paramGroupid === $groupid
                     && $tokens[$tag]['content'] !== '@param'
                 ) {
                     $error = 'Tag %s cannot be grouped with parameter tags in a doc comment';
                     $data  = [$tokens[$tag]['content']];
-                    $phpcsFile->addError($error, $tag, 'NonParamGroup', $data);
-                }
+
+                    if ($canFixNonParamGroup === true) {
+                        $canFixNonParamGroup = $phpcsFile->addFixableError($error, $tag, 'NonParamGroup', $data);
+                    } else {
+                        $phpcsFile->addError($error, $tag, 'NonParamGroup', $data);
+                    }
+
+                    if ($canFixNonParamGroup === true) {
+                        $phpcsFile->fixer->beginChangeset();
+
+                        if ($pos > 0) {
+                            $thisTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $tag, $commentStart, false, $phpcsFile->eolChar));
+                            $phpcsFile->fixer->addContentBefore($thisTagLineStart, $indent.'*'.$phpcsFile->eolChar);
+                        } else {
+                            $nextTag          = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($tag + 1), $commentEnd);
+                            $nextTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $nextTag, $commentStart, false, $phpcsFile->eolChar));
+                            $phpcsFile->fixer->addContentBefore($nextTagLineStart, $indent.'*'.$phpcsFile->eolChar);
+                        }
+
+                        $phpcsFile->fixer->endChangeset();
+                        $canFixNonParamGroup = false;
+                    }
+                }//end if
 
                 $tagLength = $tokens[$tag]['length'];
                 if ($tagLength > $maxLength) {
@@ -277,7 +396,7 @@ public function process(File $phpcsFile, $stackPtr)
                 if ($string !== false && $tokens[$string]['line'] === $tokens[$tag]['line']) {
                     $paddings[$tag] = $tokens[($tag + 1)]['length'];
                 }
-            }
+            }//end foreach
 
             // Check that there was single blank line after the tag block
             // but account for a multi-line tag comments.
@@ -298,7 +417,6 @@ public function process(File $phpcsFile, $stackPtr)
                             $phpcsFile->fixer->replaceToken($i, '');
                         }
 
-                        $indent = str_repeat(' ', $tokens[$stackPtr]['column']);
                         $phpcsFile->fixer->addContent($prev, $phpcsFile->eolChar.$indent.'*'.$phpcsFile->eolChar);
                         $phpcsFile->fixer->endChangeset();
                     }
@@ -328,8 +446,45 @@ public function process(File $phpcsFile, $stackPtr)
         // If there is a param group, it needs to be first.
         if ($paramGroupid !== null && $paramGroupid !== 0) {
             $error = 'Parameter tags must be defined first in a doc comment';
-            $phpcsFile->addError($error, $tagGroups[$paramGroupid][0], 'ParamNotFirst');
-        }
+            $fix   = $phpcsFile->addFixableError($error, $tagGroups[$paramGroupid][0], 'ParamNotFirst');
+
+            if ($fix === true) {
+                $phpcsFile->fixer->beginChangeset();
+
+                $firstTag      = $phpcsFile->findNext(T_DOC_COMMENT_TAG, $stackPtr, $commentEnd);
+                $firstParamTag = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($firstTag + 1), $commentEnd, false, '@param');
+                if ($firstTagAfterParams === null) {
+                    $firstTagAfterParams = $commentEnd;
+                }
+
+                $lineBetween = ($tokens[$firstParamTag]['line'] - 1);
+
+                $tagGroupOne = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $firstTag, $commentStart, false, $phpcsFile->eolChar));
+                $tagGroupTwo = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $firstParamTag, $commentStart, false, $phpcsFile->eolChar));
+                $markerThree = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $firstTagAfterParams, $commentStart, false, $phpcsFile->eolChar));
+
+                $otherContent = $tokens[$tagGroupOne]['content'];
+                for ($i = ($tagGroupOne + 1); $i < $tagGroupTwo; $i++) {
+                    if ($tokens[$i]['line'] === $lineBetween) {
+                        break;
+                    }
+
+                    $otherContent .= $tokens[$i]['content'];
+                    $phpcsFile->fixer->replaceToken($i, '');
+                }
+
+                $paramContent = $tokens[$tagGroupTwo]['content'];
+                for ($i = ($tagGroupTwo + 1); $i < $markerThree; $i++) {
+                    $paramContent .= $tokens[$i]['content'];
+                    $phpcsFile->fixer->replaceToken($i, '');
+                }
+
+                $phpcsFile->fixer->replaceToken($tagGroupOne, $paramContent);
+                $phpcsFile->fixer->replaceToken($tagGroupTwo, $otherContent);
+
+                $phpcsFile->fixer->endChangeset();
+            }//end if
+        }//end if
 
         $foundTags = [];
         foreach ($tokens[$stackPtr]['comment_tags'] as $pos => $tag) {
@@ -338,14 +493,46 @@ public function process(File $phpcsFile, $stackPtr)
                 $lastTag = $tokens[$stackPtr]['comment_tags'][($pos - 1)];
                 if ($tokens[$lastTag]['content'] !== $tagName) {
                     $error = 'Tags must be grouped together in a doc comment';
-                    $phpcsFile->addError($error, $tag, 'TagsNotGrouped');
-                }
+                    $fix   = $phpcsFile->addFixableError($error, $tag, 'TagsNotGrouped');
+
+                    if ($fix === true) {
+                        $phpcsFile->fixer->beginChangeset();
+
+                        $prevTag          = $phpcsFile->findPrevious(T_DOC_COMMENT_TAG, ($tag - 1), $commentStart);
+                        $prevTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $prevTag, $commentStart, false, $phpcsFile->eolChar));
+                        $thisTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $tag, $commentStart, false, $phpcsFile->eolChar));
+
+                        if (isset($tokens[$stackPtr]['comment_tags'][($pos + 1)]) === true) {
+                            $nextTag          = $phpcsFile->findNext(T_DOC_COMMENT_TAG, ($tag + 1), $commentEnd);
+                            $nextTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $nextTag, $commentStart, false, $phpcsFile->eolChar));
+                        } else {
+                            $nextTagLineStart = (1 + $phpcsFile->findPrevious(T_DOC_COMMENT_WHITESPACE, $commentEnd, $commentStart, false, $phpcsFile->eolChar));
+                        }
+
+                        $prevTagContent = $tokens[$prevTagLineStart]['content'];
+                        for ($i = ($prevTagLineStart + 1); $i < $thisTagLineStart; $i++) {
+                            $prevTagContent .= $tokens[$i]['content'];
+                            $phpcsFile->fixer->replaceToken($i, '');
+                        }
+
+                        $thisTagContent = $tokens[$thisTagLineStart]['content'];
+                        for ($i = ($thisTagLineStart + 1); $i < $nextTagLineStart; $i++) {
+                            $thisTagContent .= $tokens[$i]['content'];
+                            $phpcsFile->fixer->replaceToken($i, '');
+                        }
+
+                        $phpcsFile->fixer->replaceToken($prevTagLineStart, $thisTagContent);
+                        $phpcsFile->fixer->replaceToken($thisTagLineStart, $prevTagContent);
+
+                        $phpcsFile->fixer->endChangeset();
+                    }//end if
+                }//end if
 
                 continue;
-            }
+            }//end if
 
             $foundTags[$tagName] = true;
-        }
+        }//end foreach
 
     }//end process()
 
diff --git a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.inc b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.inc
index 81366272c9..b4a9668a80 100644
--- a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.inc
+++ b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.inc
@@ -64,9 +64,9 @@
  * Short description.
  *
  *
- * @param
+ * @param one
  *
- * @param
+ * @param two
  *
  *
  * @tag one
@@ -163,6 +163,27 @@
  * @three bar
  */
 
+/**
+ * @one
+ * @two
+ * @three
+ * @four
+ * @one
+ * @two
+ * @three
+ * @four
+ */
+
+/**
+ * @one this has more than one line (1)
+ *      and should remain with the first tag (1)
+ * @two a different tag which should be (2)
+ *      moved to after the third tag (2)
+ * @one the same tag as the first but listed (3)
+ *      after a different tag; this should be (3)
+ *      moved above the second tag (3)
+ */
+
 /**
  * @ var Comment
  */
@@ -249,4 +270,8 @@
  * @link		http://pear.php.net/package/PHP_CodeSniffer
  */
 
+/**
+ *
+ */
+
 /** No docblock close tag. Must be last test without new line.
\ No newline at end of file
diff --git a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.inc.fixed b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.inc.fixed
index 43ce064a5d..12c8719787 100644
--- a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.inc.fixed
+++ b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.inc.fixed
@@ -11,9 +11,9 @@
  */
 
 /**
- * short description
+ * Short description
  *
- * long description
+ * Long description
  * over multiple lines.
  *
  * @tag1 one
@@ -44,10 +44,10 @@
 /**
  * Short description.
  *
- * @tag one
- *
  * @param
  * @param
+ *
+ * @tag one
  */
 
 /**
@@ -55,15 +55,15 @@
  *
  * @param
  * @param
- * @tag   one
+ *
+ * @tag one
  */
 
 /**
  * Short description.
  *
- * @param
- *
- * @param
+ * @param one
+ * @param two
  *
  * @tag one
  */
@@ -72,9 +72,9 @@
  * Short description.
  *
  * @param
- *
- * @tag   one
  * @param
+ *
+ * @tag one
  */
 
 /**
@@ -147,9 +147,9 @@
  * Comment
  *
  * @one
- * @two
  * @one
  *
+ * @two
  * @two   something
  *        here
  * @two   foo
@@ -158,6 +158,27 @@
  * @three bar
  */
 
+/**
+ * @one
+ * @one
+ * @two
+ * @two
+ * @three
+ * @three
+ * @four
+ * @four
+ */
+
+/**
+ * @one this has more than one line (1)
+ *      and should remain with the first tag (1)
+ * @one the same tag as the first but listed (3)
+ *      after a different tag; this should be (3)
+ *      moved above the second tag (3)
+ * @two a different tag which should be (2)
+ *      moved to after the third tag (2)
+ */
+
 /**
  * @ var Comment
  */
@@ -180,27 +201,31 @@
  */
 
 /**
- * this is a test
+ * This is a test
+ *
+ * @param boolean $foo blah
+ * @param boolean $bar Blah.
  *
  * @author test
- * @param  boolean $foo blah
+ *
  * @return boolean
- * @param  boolean $bar Blah.
  */
 
 /**
  * Short description.
  *
+ * @param int    $number
+ * @param string $text
+ *
  * @tag    one
- * @param  int    $number
- * @param  string $text
  * @return something
  */
 
 /**
  *
- * @param  int    $number
- * @param  string $text
+ * @param int    $number
+ * @param string $text
+ *
  * @return something
  */
 
@@ -209,11 +234,11 @@
  */
 
 /**
- * étude des ...
+ * Étude des ...
  */
 
 /**
-* doc comment 
+* Doc comment 
 */
 
         /**
@@ -221,7 +246,8 @@
          *
          * @param
          * @param
-         * @tag   one
+         *
+         * @tag one
          */
 
         /**
@@ -254,4 +280,5 @@
  * @link      http://pear.php.net/package/PHP_CodeSniffer
  */
 
+
 /** No docblock close tag. Must be last test without new line.
\ No newline at end of file
diff --git a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.php b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.php
index 57937581ba..4049cb39cc 100644
--- a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.php
+++ b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.php
@@ -64,30 +64,38 @@ public function getErrorList()
             95  => 1,
             156 => 1,
             158 => 1,
-            170 => 3,
-            171 => 3,
-            179 => 1,
-            183 => 1,
-            184 => 2,
-            185 => 1,
-            186 => 1,
-            187 => 2,
-            193 => 1,
-            196 => 1,
-            199 => 1,
-            203 => 1,
+            166 => 1,
+            171 => 1,
+            172 => 1,
+            173 => 1,
+            174 => 1,
+            177 => 1,
+            182 => 1,
+            191 => 3,
+            192 => 3,
+            200 => 1,
+            204 => 1,
+            205 => 2,
             206 => 1,
-            211 => 1,
-            214 => 4,
-            218 => 1,
-            220 => 2,
-            222 => 1,
-            224 => 3,
+            207 => 1,
+            208 => 2,
+            214 => 1,
+            217 => 1,
+            220 => 1,
+            224 => 1,
+            227 => 1,
+            232 => 1,
+            235 => 4,
+            239 => 1,
+            241 => 2,
             243 => 1,
-            244 => 1,
-            246 => 1,
-            248 => 1,
-            249 => 1,
+            245 => 3,
+            264 => 1,
+            265 => 1,
+            267 => 1,
+            269 => 1,
+            270 => 1,
+            273 => 1,
         ];
 
     }//end getErrorList()

From 4673571130f61b07a4b7f7adf0385739fb5f7027 Mon Sep 17 00:00:00 2001
From: Dan Wallis <dan@wallis.nz>
Date: Sat, 4 Feb 2023 18:50:06 +0000
Subject: [PATCH 2/7] Remove use of null coalesce operator

---
 .../Sniffs/Commenting/DocCommentSniff.php     | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
index daef9be1f7..4819e2f3af 100644
--- a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
+++ b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
@@ -79,16 +79,16 @@ public function process(File $phpcsFile, $stackPtr)
                     $phpcsFile->fixer->replaceToken($i, '');
                 }
 
-                $tokenBefore = ($tokens[($commentStart - 1)] ?? null);
-                $tokenAfter  = ($tokens[($commentEnd + 1)] ?? null);
-                if ($tokenBefore !== null
-                    && $tokenBefore['code'] === T_WHITESPACE
-                    && $tokenBefore['content'] === $phpcsFile->eolChar
-                    && $tokenAfter !== null
-                    && $tokenAfter['code'] === T_WHITESPACE
-                    && $tokenAfter['content'] === $phpcsFile->eolChar
-                ) {
-                    $phpcsFile->fixer->replaceToken(($commentStart - 1), '');
+                if (isset($tokens[($commentStart - 1)]) === true && isset($tokens[($commentEnd + 1)]) === true) {
+                    $tokenBefore = $tokens[($commentStart - 1)];
+                    $tokenAfter  = $tokens[($commentEnd + 1)];
+                    if ($tokenBefore['code'] === T_WHITESPACE
+                        && $tokenBefore['content'] === $phpcsFile->eolChar
+                        && $tokenAfter['code'] === T_WHITESPACE
+                        && $tokenAfter['content'] === $phpcsFile->eolChar
+                    ) {
+                        $phpcsFile->fixer->replaceToken(($commentStart - 1), '');
+                    }
                 }
 
                 $phpcsFile->fixer->endChangeset();

From 7c9ded458091c2ae3a7184de805dfc42846aac61 Mon Sep 17 00:00:00 2001
From: Dan Wallis <dan@wallis.nz>
Date: Sun, 5 Feb 2023 18:54:39 +0000
Subject: [PATCH 3/7] Avoid setting default for variable

---
 .../Sniffs/Commenting/DocCommentSniff.php       | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
index 4819e2f3af..9fb7744476 100644
--- a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
+++ b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
@@ -182,18 +182,17 @@ public function process(File $phpcsFile, $stackPtr)
 
                 $firstCharacter      = mb_substr($shortContent, 0, 1);
                 $firstCharacterUpper = mb_strtoupper($firstCharacter);
-                $fix = false;
 
-                if ($firstCharacter !== $firstCharacterUpper) {
-                    $fix = $phpcsFile->addFixableError($error, $short, 'ShortNotCapital');
-                } else {
+                if ($firstCharacter === $firstCharacterUpper) {
                     $phpcsFile->addError($error, $short, 'ShortNotCapital');
-                }
+                } else {
+                    $fix = $phpcsFile->addFixableError($error, $short, 'ShortNotCapital');
 
-                if ($fix === true) {
-                    $phpcsFile->fixer->beginChangeset();
-                    $phpcsFile->fixer->replaceToken($short, $firstCharacterUpper.mb_substr($tokens[$short]['content'], 1));
-                    $phpcsFile->fixer->endChangeset();
+                    if ($fix === true) {
+                        $phpcsFile->fixer->beginChangeset();
+                        $phpcsFile->fixer->replaceToken($short, $firstCharacterUpper.mb_substr($tokens[$short]['content'], 1));
+                        $phpcsFile->fixer->endChangeset();
+                    }
                 }
             }
 

From df3b5c5aac6d16b1b77586d3661cfe5dc2c18871 Mon Sep 17 00:00:00 2001
From: Dan Wallis <dan@wallis.nz>
Date: Sun, 5 Feb 2023 18:57:11 +0000
Subject: [PATCH 4/7] Avoid setting default variable

---
 .../Sniffs/Commenting/DocCommentSniff.php       | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
index 9fb7744476..4a1d6c8276 100644
--- a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
+++ b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
@@ -222,18 +222,17 @@ public function process(File $phpcsFile, $stackPtr)
 
                     $firstCharacter      = mb_substr($tokens[$long]['content'][0], 0, 1);
                     $firstCharacterUpper = mb_strtoupper($firstCharacter);
-                    $fix = false;
 
-                    if ($firstCharacter !== $firstCharacterUpper) {
-                        $fix = $phpcsFile->addFixableError($error, $long, 'LongNotCapital');
-                    } else {
+                    if ($firstCharacter === $firstCharacterUpper) {
                         $phpcsFile->addError($error, $long, 'LongNotCapital');
-                    }
+                    } else {
+                        $fix = $phpcsFile->addFixableError($error, $long, 'LongNotCapital');
 
-                    if ($fix === true) {
-                        $phpcsFile->fixer->beginChangeset();
-                        $phpcsFile->fixer->replaceToken($long, $firstCharacterUpper.mb_substr($tokens[$long]['content'], 1));
-                        $phpcsFile->fixer->endChangeset();
+                        if ($fix === true) {
+                            $phpcsFile->fixer->beginChangeset();
+                            $phpcsFile->fixer->replaceToken($long, $firstCharacterUpper.mb_substr($tokens[$long]['content'], 1));
+                            $phpcsFile->fixer->endChangeset();
+                        }
                     }
                 }
             }//end if

From 88ac1123066e1e3526c666886952d92547455c7d Mon Sep 17 00:00:00 2001
From: Dan Wallis <dan@wallis.nz>
Date: Wed, 29 Mar 2023 17:04:51 +0100
Subject: [PATCH 5/7] Fix problem identified by broken unit test

---
 .../Sniffs/Commenting/DocCommentSniff.php     |  5 ++
 .../Tests/Commenting/DocCommentUnitTest.js    | 41 ++++++++--
 .../Commenting/DocCommentUnitTest.js.fixed    | 81 ++++++++++++-------
 3 files changed, 92 insertions(+), 35 deletions(-)

diff --git a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
index 4a1d6c8276..374a3ac750 100644
--- a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
+++ b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
@@ -332,6 +332,11 @@ public function process(File $phpcsFile, $stackPtr)
                             || $tokens[($insertionPointer + 2)]['content'] !== $phpcsFile->eolChar
                         ) {
                             $insertionPointer++;
+
+                            if (($insertionPointer + 2) >= $commentEnd) {
+                                $insertionPointer = $commentEnd - 1;
+                                break;
+                            }
                         }
 
                         $phpcsFile->fixer->addContentBefore($insertionPointer, $thisTagContent);
diff --git a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.js b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.js
index b3283f7853..0a8a9792ea 100644
--- a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.js
+++ b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.js
@@ -64,15 +64,15 @@
  * Short description.
  *
  *
- * @param
+ * @param one
  *
- * @param
+ * @param two
  *
  *
  * @tag one
  */
 
- /**
+/**
  * Short description.
  *
  * @param
@@ -95,7 +95,7 @@
  * @g3  two
  */
 
- /**
+/**
  * Short description
  * over multiple lines.
  *
@@ -117,7 +117,7 @@
  *             multiple lines
  */
 
- /**
+/**
  * Returns true if the specified string is in the camel caps format.
  *
  * @param boolean $classFormat If true, check to see if the string is in the
@@ -132,7 +132,7 @@
  * @return boolean
  */
 
- /**
+/**
  * Verifies that a @throws tag exists for a function that throws exceptions.
  * Verifies the number of @throws tags and the number of throw tokens matches.
  * Verifies the exception type.
@@ -148,7 +148,7 @@
  * @link      http://pear.php.net/package/PHP_CodeSniffer
  */
 
- /**
+/**
  * Comment
  *
  * @one
@@ -163,7 +163,28 @@
  * @three bar
  */
 
- /**
+/**
+ * @one
+ * @two
+ * @three
+ * @four
+ * @one
+ * @two
+ * @three
+ * @four
+ */
+
+/**
+ * @one this has more than one line (1)
+ *      and should remain with the first tag (1)
+ * @two a different tag which should be (2)
+ *      moved to after the third tag (2)
+ * @one the same tag as the first but listed (3)
+ *      after a different tag; this should be (3)
+ *      moved above the second tag (3)
+ */
+
+/**
  * @ var Comment
  */
 
@@ -248,3 +269,7 @@
  * @license	  	https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
  * @link		http://pear.php.net/package/PHP_CodeSniffer
  */
+
+/**
+ *
+ */
diff --git a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.js.fixed b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.js.fixed
index 0df0687a2f..999872c5c4 100644
--- a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.js.fixed
+++ b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.js.fixed
@@ -11,9 +11,9 @@
  */
 
 /**
- * short description
+ * Short description
  *
- * long description
+ * Long description
  * over multiple lines.
  *
  * @tag1 one
@@ -44,10 +44,10 @@
 /**
  * Short description.
  *
- * @tag one
- *
  * @param
  * @param
+ *
+ * @tag one
  */
 
 /**
@@ -55,26 +55,26 @@
  *
  * @param
  * @param
- * @tag   one
+ *
+ * @tag one
  */
 
 /**
  * Short description.
  *
- * @param
- *
- * @param
+ * @param one
+ * @param two
  *
  * @tag one
  */
 
- /**
+/**
  * Short description.
  *
  * @param
- *
- * @tag   one
  * @param
+ *
+ * @tag one
  */
 
 /**
@@ -90,7 +90,7 @@
  * @g3 two
  */
 
- /**
+/**
  * Short description
  * over multiple lines.
  *
@@ -112,7 +112,7 @@
  *             multiple lines
  */
 
- /**
+/**
  * Returns true if the specified string is in the camel caps format.
  *
  * @param boolean $classFormat If true, check to see if the string is in the
@@ -127,7 +127,7 @@
  * @return boolean
  */
 
- /**
+/**
  * Verifies that a @throws tag exists for a function that throws exceptions.
  * Verifies the number of @throws tags and the number of throw tokens matches.
  * Verifies the exception type.
@@ -143,13 +143,13 @@
  * @link      http://pear.php.net/package/PHP_CodeSniffer
  */
 
- /**
+/**
  * Comment
  *
  * @one
- * @two
  * @one
  *
+ * @two
  * @two   something
  *        here
  * @two   foo
@@ -158,7 +158,28 @@
  * @three bar
  */
 
- /**
+/**
+ * @one
+ * @one
+ * @two
+ * @two
+ * @three
+ * @three
+ * @four
+ * @four
+ */
+
+/**
+ * @one this has more than one line (1)
+ *      and should remain with the first tag (1)
+ * @one the same tag as the first but listed (3)
+ *      after a different tag; this should be (3)
+ *      moved above the second tag (3)
+ * @two a different tag which should be (2)
+ *      moved to after the third tag (2)
+ */
+
+/**
  * @ var Comment
  */
 
@@ -180,27 +201,31 @@
  */
 
 /**
- * this is a test
+ * This is a test
+ *
+ * @param boolean $foo blah
+ * @param boolean $bar Blah.
  *
  * @author test
- * @param  boolean $foo blah
+ *
  * @return boolean
- * @param  boolean $bar Blah.
  */
 
 /**
  * Short description.
  *
+ * @param int    $number
+ * @param string $text
+ *
  * @tag    one
- * @param  int    $number
- * @param  string $text
  * @return something
  */
 
 /**
  *
- * @param  int    $number
- * @param  string $text
+ * @param int    $number
+ * @param string $text
+ *
  * @return something
  */
 
@@ -209,11 +234,11 @@
  */
 
 /**
- * étude des ...
+ * Étude des ...
  */
 
 /**
-* doc comment 
+* Doc comment 
 */
 
         /**
@@ -221,7 +246,8 @@
          *
          * @param
          * @param
-         * @tag   one
+         *
+         * @tag one
          */
 
         /**
@@ -253,3 +279,4 @@
  * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
  * @link      http://pear.php.net/package/PHP_CodeSniffer
  */
+

From c0d95edd6ddb42d62ca36ebf4d63b02cc4b77d83 Mon Sep 17 00:00:00 2001
From: Dan Wallis <dan@wallis.nz>
Date: Sat, 17 Jun 2023 14:05:08 +0100
Subject: [PATCH 6/7] Remove 'risky' fixer for {Short,Long}NotCapital

---
 .../Sniffs/Commenting/DocCommentSniff.php     | 32 ++-----------------
 .../Commenting/DocCommentUnitTest.inc.fixed   | 10 +++---
 .../Commenting/DocCommentUnitTest.js.fixed    | 10 +++---
 3 files changed, 12 insertions(+), 40 deletions(-)

diff --git a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
index 374a3ac750..a9cdc3a3a5 100644
--- a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
+++ b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
@@ -179,21 +179,7 @@ public function process(File $phpcsFile, $stackPtr)
 
             if (preg_match('/^\p{Ll}/u', $shortContent) === 1) {
                 $error = 'Doc comment short description must start with a capital letter';
-
-                $firstCharacter      = mb_substr($shortContent, 0, 1);
-                $firstCharacterUpper = mb_strtoupper($firstCharacter);
-
-                if ($firstCharacter === $firstCharacterUpper) {
-                    $phpcsFile->addError($error, $short, 'ShortNotCapital');
-                } else {
-                    $fix = $phpcsFile->addFixableError($error, $short, 'ShortNotCapital');
-
-                    if ($fix === true) {
-                        $phpcsFile->fixer->beginChangeset();
-                        $phpcsFile->fixer->replaceToken($short, $firstCharacterUpper.mb_substr($tokens[$short]['content'], 1));
-                        $phpcsFile->fixer->endChangeset();
-                    }
-                }
+                $phpcsFile->addError($error, $short, 'ShortNotCapital');
             }
 
             $long = $phpcsFile->findNext($empty, ($shortEnd + 1), ($commentEnd - 1), true);
@@ -219,21 +205,7 @@ public function process(File $phpcsFile, $stackPtr)
 
                 if (preg_match('/^\p{Ll}/u', $tokens[$long]['content']) === 1) {
                     $error = 'Doc comment long description must start with a capital letter';
-
-                    $firstCharacter      = mb_substr($tokens[$long]['content'][0], 0, 1);
-                    $firstCharacterUpper = mb_strtoupper($firstCharacter);
-
-                    if ($firstCharacter === $firstCharacterUpper) {
-                        $phpcsFile->addError($error, $long, 'LongNotCapital');
-                    } else {
-                        $fix = $phpcsFile->addFixableError($error, $long, 'LongNotCapital');
-
-                        if ($fix === true) {
-                            $phpcsFile->fixer->beginChangeset();
-                            $phpcsFile->fixer->replaceToken($long, $firstCharacterUpper.mb_substr($tokens[$long]['content'], 1));
-                            $phpcsFile->fixer->endChangeset();
-                        }
-                    }
+                    $phpcsFile->addError($error, $long, 'LongNotCapital');
                 }
             }//end if
         }//end if
diff --git a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.inc.fixed b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.inc.fixed
index 12c8719787..ba008adbec 100644
--- a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.inc.fixed
+++ b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.inc.fixed
@@ -11,9 +11,9 @@
  */
 
 /**
- * Short description
+ * short description
  *
- * Long description
+ * long description
  * over multiple lines.
  *
  * @tag1 one
@@ -201,7 +201,7 @@
  */
 
 /**
- * This is a test
+ * this is a test
  *
  * @param boolean $foo blah
  * @param boolean $bar Blah.
@@ -234,11 +234,11 @@
  */
 
 /**
- * Étude des ...
+ * étude des ...
  */
 
 /**
-* Doc comment 
+* doc comment 
 */
 
         /**
diff --git a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.js.fixed b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.js.fixed
index 999872c5c4..1b42f61657 100644
--- a/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.js.fixed
+++ b/src/Standards/Generic/Tests/Commenting/DocCommentUnitTest.js.fixed
@@ -11,9 +11,9 @@
  */
 
 /**
- * Short description
+ * short description
  *
- * Long description
+ * long description
  * over multiple lines.
  *
  * @tag1 one
@@ -201,7 +201,7 @@
  */
 
 /**
- * This is a test
+ * this is a test
  *
  * @param boolean $foo blah
  * @param boolean $bar Blah.
@@ -234,11 +234,11 @@
  */
 
 /**
- * Étude des ...
+ * étude des ...
  */
 
 /**
-* Doc comment 
+* doc comment 
 */
 
         /**

From 73a1afd080d1d28f6bb5cf0cdb96f1f0ac284175 Mon Sep 17 00:00:00 2001
From: Dan Wallis <dan@wallis.nz>
Date: Sat, 17 Jun 2023 14:13:06 +0100
Subject: [PATCH 7/7] phpcbf

---
 src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
index a9cdc3a3a5..ac678a6404 100644
--- a/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
+++ b/src/Standards/Generic/Sniffs/Commenting/DocCommentSniff.php
@@ -306,7 +306,7 @@ public function process(File $phpcsFile, $stackPtr)
                             $insertionPointer++;
 
                             if (($insertionPointer + 2) >= $commentEnd) {
-                                $insertionPointer = $commentEnd - 1;
+                                $insertionPointer = ($commentEnd - 1);
                                 break;
                             }
                         }