PEAR/FunctionDeclaration: bug fix - block comment handling

When a block comment is multi-line, the first `T_COMMENT` token will start with the `/*`, but `T_COMMENT` tokens which are part of the block comment on subsequent lines will include the indentation in the `T_COMMENT` token.
This makes these tokens more complex to deal with in sniffs, especially for indentation calculations.

The `PEAR.Functions.FunctionDeclaration` sniff did not take the possibility of a multi-line block comment being part of the signature of a multi-line function declaration into account (at all).
This also affected, by extension, the `Squiz.Functions.MultiLineFunctionDeclaration` sniff and would cause a fixer conflict of the sniff with itself.

This commit fixes this.

Includes extensive tests.

Note - there are two caveats to the fix:
1. If subsequent lines in a block comment are not prefixed with a `*`, the indentation fix will not be precise, but will be a best-effort "indent needs to be the same or larger than the expected indent".
2. Like for all sniffs, lines containing PHPCS annotations will be ignored unless the `--ignore-annotations` CLI flag is used.
    That also applies to these lines when they are part of a multi-line block comment.

Fixes 1368

Author: jrfnl

src/Standards/PEAR/Sniffs/Functions/FunctionDeclarationSniff.php

@@ -468,6 +468,30 @@ public function processArgumentList(File $phpcsFile, int $stackPtr, int $indent,
                 } elseif ($tokens[$i]['code'] === T_DOC_COMMENT_WHITESPACE) {
                     $foundIndent = $tokens[$i]['length'];
                     ++$expectedIndent;
+                } elseif (($tokens[$i]['code'] === T_COMMENT
+                    || isset(Tokens::PHPCS_ANNOTATION_TOKENS[$tokens[$i]['code']]) === true)
+                    && (($tokens[($i - 1)]['code'] === T_COMMENT
+                    || isset(Tokens::PHPCS_ANNOTATION_TOKENS[$tokens[($i - 1)]['code']]) === true)
+                    && $tokens[($i - 1)]['line'] === $lastLine)
+                ) {
+                    // This is the second line of a multi-line comment.
+                    // This token _may_ include indentation whitespace if this is part of a block comment.
+                    $trimmedContent = ltrim($tokens[$i]['content']);
+                    $trimmedLength  = strlen($trimmedContent);
+                    if ($trimmedLength === 0) {
+                        // This is a blank comment line, so indenting it is pointless.
+                        $lastLine = $tokens[$i]['line'];
+                        continue;
+                    }
+
+                    $foundIndent = (strlen($tokens[$i]['content']) - $trimmedLength);
+                    if ($trimmedContent[0] === '*') {
+                        ++$expectedIndent;
+                    } elseif ($foundIndent >= $expectedIndent) {
+                        // Multi-line block comment, not star-aligned. These may contain extra indent.
+                        $lastLine = $tokens[$i]['line'];
+                        continue;
+                    }
                 }
 
                 if ($expectedIndent !== $foundIndent) {
@@ -480,8 +504,13 @@ public function processArgumentList(File $phpcsFile, int $stackPtr, int $indent,
                     $fix = $phpcsFile->addFixableError($error, $i, 'Indent', $data);
                     if ($fix === true) {
                         $spaces = str_repeat(' ', $expectedIndent);
+
                         if ($foundIndent === 0) {
                             $phpcsFile->fixer->addContentBefore($i, $spaces);
+                        } elseif ($tokens[$i]['code'] === T_COMMENT
+                            || isset(Tokens::PHPCS_ANNOTATION_TOKENS[$tokens[$i]['code']]) === true
+                        ) {
+                            $phpcsFile->fixer->replaceToken($i, $spaces . ltrim($tokens[$i]['content']));
                         } else {
                             $phpcsFile->fixer->replaceToken($i, $spaces);
                         }

src/Standards/PEAR/Tests/Functions/FunctionDeclarationUnitTest.1.inc

@@ -488,3 +488,55 @@ function foo(
     $param2
 ) : // comment.
    \Package\Sub\SomeClass   {}
+
+class MultiLineCommentsBetweenParamsIndentOK
+{
+    public function something(
+        /*
+         * Some comment for whatever reason
+         * phpcs:disable Stnd.Cat -- for reasons
+         */
+        string $paramA,
+        // phpcs:enable Stnd.Cat
+        // Comment line 2
+        // Comment line 3
+        #[NotBlank]
+        int $paramB,
+    ) {
+    }
+}
+
+class MultiLineCommentsBetweenParamsIncorrectIndent
+{
+    public function something(
+    /*
+     * Some comment for whatever reason
+     * phpcs:disable Stnd.CatA -- this line will only be flagged & fixed when `--ignore-annotations` is used.
+     */
+    string $paramA,
+/*
+ * Some comment for whatever reason
+ * phpcs:disable Stnd.CatB -- this line will only be flagged & fixed when `--ignore-annotations` is used.
+ */
+string $paramB,
+
+  // phpcs:enable Stnd.CatA,Stnd.CatB -- this line will only be flagged & fixed when `--ignore-annotations` is used.
+    // Comment line 2
+// Comment line 3
+#[NotBlank]
+int $paramC,
+            /*
+
+                Some comment surrounded by blank lines (deliberately!)
+
+             */
+            ?string $paramD,
+    /*
+
+      Some comment surrounded by blank lines (deliberately!)
+
+     */
+    ?string $paramE,
+    ) {
+    }
+}

src/Standards/PEAR/Tests/Functions/FunctionDeclarationUnitTest.1.inc.fixed

@@ -485,3 +485,54 @@ function foo(
     $param2
 ) : // comment.
    \Package\Sub\SomeClass {}
+
+class MultiLineCommentsBetweenParamsIndentOK
+{
+    public function something(
+        /*
+         * Some comment for whatever reason
+         * phpcs:disable Stnd.Cat -- for reasons
+         */
+        string $paramA,
+        // phpcs:enable Stnd.Cat
+        // Comment line 2
+        // Comment line 3
+        #[NotBlank]
+        int $paramB,
+    ) {
+    }
+}
+
+class MultiLineCommentsBetweenParamsIncorrectIndent
+{
+    public function something(
+        /*
+         * Some comment for whatever reason
+     * phpcs:disable Stnd.CatA -- this line will only be flagged & fixed when `--ignore-annotations` is used.
+         */
+        string $paramA,
+        /*
+         * Some comment for whatever reason
+ * phpcs:disable Stnd.CatB -- this line will only be flagged & fixed when `--ignore-annotations` is used.
+         */
+        string $paramB,
+  // phpcs:enable Stnd.CatA,Stnd.CatB -- this line will only be flagged & fixed when `--ignore-annotations` is used.
+        // Comment line 2
+        // Comment line 3
+        #[NotBlank]
+        int $paramC,
+        /*
+
+                Some comment surrounded by blank lines (deliberately!)
+
+         */
+        ?string $paramD,
+        /*
+
+        Some comment surrounded by blank lines (deliberately!)
+
+         */
+        ?string $paramE,
+    ) {
+    }
+}

src/Standards/PEAR/Tests/Functions/FunctionDeclarationUnitTest.php

@@ -109,6 +109,26 @@ public function getErrorList($testFile = '')
                     475 => 1,
                     483 => 1,
                     490 => 2,
+                    512 => 1,
+                    513 => 1,
+                    515 => 1,
+                    516 => 1,
+                    517 => 1,
+                    518 => 1,
+                    520 => 1,
+                    521 => 1,
+                    522 => 1,
+                    524 => 1,
+                    525 => 1,
+                    526 => 1,
+                    527 => 1,
+                    528 => 1,
+                    532 => 1,
+                    533 => 1,
+                    534 => 1,
+                    536 => 1,
+                    538 => 1,
+                    539 => 1,
                 ];
 
             case 'FunctionDeclarationUnitTest.4.inc':