From 30d18970455ea356cc24212091969e078a3b154f Mon Sep 17 00:00:00 2001 From: Dan Wallis 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 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 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 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 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 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 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; } }