Generic/OpeningFunctionBraceBsdAllman: bug fix - prevent removing return types

As reported in 3357, the `Generic.Functions.OpeningFunctionBraceBsdAllman` sniff would remove return types (and comments) when fixing code where blank lines existed between the end of the function declaration and the open brace.

This commit fixes that bug.

In the case of comments, the `BraceSpacing` error will no longer auto-fix as a dev should decide where the comment should go and/or whether it should be removed.

Includes unit tests.

Fixes 3357

Author: jrfnl

src/Standards/Generic/Sniffs/Functions/OpeningFunctionBraceBsdAllmanSniff.php

@@ -139,17 +139,31 @@ public function process(File $phpcsFile, $stackPtr)
         } else if ($lineDifference > 1) {
             $error = 'Opening brace should be on the line after the declaration; found %s blank line(s)';
             $data  = [($lineDifference - 1)];
-            $fix   = $phpcsFile->addFixableError($error, $openingBrace, 'BraceSpacing', $data);
-            if ($fix === true) {
-                for ($i = ($tokens[$stackPtr]['parenthesis_closer'] + 1); $i < $openingBrace; $i++) {
-                    if ($tokens[$i]['line'] === $braceLine) {
-                        $phpcsFile->fixer->addNewLineBefore($i);
-                        break;
+
+            $prevNonWs = $phpcsFile->findPrevious(T_WHITESPACE, ($openingBrace - 1), $closeBracket, true);
+            if ($prevNonWs !== $prev) {
+                // There must be a comment between the end of the function declaration and the open brace.
+                // Report, but don't fix.
+                $phpcsFile->addError($error, $openingBrace, 'BraceSpacing', $data);
+            } else {
+                $fix = $phpcsFile->addFixableError($error, $openingBrace, 'BraceSpacing', $data);
+                if ($fix === true) {
+                    $phpcsFile->fixer->beginChangeset();
+                    for ($i = $openingBrace; $i > $prev; $i--) {
+                        if ($tokens[$i]['line'] === $tokens[$openingBrace]['line']) {
+                            if ($tokens[$i]['column'] === 1) {
+                                $phpcsFile->fixer->addNewLineBefore($i);
+                            }
+
+                            continue;
+                        }
+
+                        $phpcsFile->fixer->replaceToken($i, '');
                     }
 
-                    $phpcsFile->fixer->replaceToken($i, '');
+                    $phpcsFile->fixer->endChangeset();
                 }
-            }
+            }//end if
         }//end if
 
         $ignore   = Tokens::$phpcsCommentTokens;

src/Standards/Generic/Tests/Functions/OpeningFunctionBraceBsdAllmanUnitTest.inc

@@ -236,3 +236,28 @@ function myFunction($a, $lot, $of, $params)
     : array /* comment */ {
     return null;
 }
+
+class Issue3357
+{
+    public function extraLine(string: $a): void
+
+    {
+        // code here.
+    }
+}
+
+function issue3357WithoutIndent(string: $a): void
+
+
+{
+    // code here.
+}
+
+class Issue3357WithComment
+{
+    public function extraLine(string: $a): void
+    // Comment.
+    {
+        // code here.
+    }
+}

src/Standards/Generic/Tests/Functions/OpeningFunctionBraceBsdAllmanUnitTest.inc.fixed

@@ -256,3 +256,25 @@ function myFunction($a, $lot, $of, $params)
 {
     return null;
 }
+
+class Issue3357
+{
+    public function extraLine(string: $a): void
+    {
+        // code here.
+    }
+}
+
+function issue3357WithoutIndent(string: $a): void
+{
+    // code here.
+}
+
+class Issue3357WithComment
+{
+    public function extraLine(string: $a): void
+    // Comment.
+    {
+        // code here.
+    }
+}

src/Standards/Generic/Tests/Functions/OpeningFunctionBraceBsdAllmanUnitTest.php

@@ -58,6 +58,9 @@ public function getErrorList()
             220 => 1,
             231 => 1,
             236 => 1,
+            244 => 1,
+            252 => 1,
+            260 => 1,
         ];
 
     }//end getErrorList()