Squiz/FunctionSpacing: fixer is broken with doc comment on closing brace line (#784)

The fixer in Squiz.WhiteSpace.FunctionSpacing gets confused when there is a doc comment on the closing brace line.

Generally speaking this sniff doesn't care about other content on the same line as the function declaration.

But in the case of a "trailing" docblock, this meant that the sniff was adding the new lines _within_ the doc block, which, in turn, meant it would still not see the "blank lines after" in the next loop, as the added lines would be seen as doc comment lines, not blank lines. Hence, the fixer conflict.

Fixed now.

Author: klausi

src/Standards/Squiz/Sniffs/WhiteSpace/FunctionSpacingSniff.php

@@ -149,6 +149,12 @@ public function process(File $phpcsFile, $stackPtr)
 
         // Allow for comments on the same line as the closer.
         for ($nextLineToken = ($closer + 1); $nextLineToken < $phpcsFile->numTokens; $nextLineToken++) {
+            // A doc comment belongs to the next statement and must not be on
+            // this line.
+            if ($tokens[$nextLineToken]['code'] === T_DOC_COMMENT_OPEN_TAG) {
+                break;
+            }
+
             if ($tokens[$nextLineToken]['line'] !== $tokens[$closer]['line']) {
                 break;
             }

src/Standards/Squiz/Tests/WhiteSpace/FunctionSpacingUnitTest.1.inc

@@ -582,3 +582,14 @@ echo 'this line belongs with the #3904 test';
 
 function Foo() {} function bar($name){}
 echo 'this line belongs with the #3904 test';
+
+
+/**
+ * foo.
+ */
+function a() {
+}/**
+ * foo.
+ */
+function b() {
+}

src/Standards/Squiz/Tests/WhiteSpace/FunctionSpacingUnitTest.1.inc.fixed

@@ -671,3 +671,17 @@ function Foo() {} function bar($name){}
 
 
 echo 'this line belongs with the #3904 test';
+
+
+/**
+ * foo.
+ */
+function a() {
+}
+
+
+/**
+ * foo.
+ */
+function b() {
+}

src/Standards/Squiz/Tests/WhiteSpace/FunctionSpacingUnitTest.php

@@ -102,6 +102,7 @@ public function getErrorList($testFile='')
                 566 => 1,
                 580 => 2,
                 583 => 3,
+                591 => 1,
             ];
 
         case 'FunctionSpacingUnitTest.2.inc':