fix: wrongly adding @return to the wrong docblock.

When a function doesn't have a docblock that is found to need a `@return`, and the function or class property above it does have a docblock, the `@return` is added to that docblock. Ergo: the wrong docblock.

The problem was that the code was finding the previous docblock in the file and treating it as if it belonged to the current function, even when there were other elements (like properties or other functions) between the docblock and the function being processed.

To fix, we validate whether the found docblock actually belongs to the function we were looking for. This is done by looking for significant tokens between the found docblock and the function. If the tokens contain anything other than function modifiers like `public`, `protected`, `abstract`, etc. then we ignore the docblock entirely and just stop processing the issue.

- Added logic in the `FunctionCommentSniff` class to check if the docblock belongs to the function and skip if it doesn't.

- Added new test functions in the test file.

Author: yCodeTech

test_utils/TestFile.php

@@ -75,6 +75,19 @@ class TestClass
      */
     private boolean|string $bar;
 
+    private function testFunctionWithoutDocblock(): string {
+        // Function without a docblock, a required `@return` tag should NOT be added to
+        // the previous docblock ($bar) (should NOT be flagged).
+        return 'Hello World';
+    }
+
+    private function anotherFunctionWithoutDocblock(): int {
+        // Function without a docblock, a required `@return` tag should NOT be added to
+        // the previous docblock ($bar) (should NOT be flagged).
+        return 42;
+    }
+
+
 
     /***************
      * TYPES TESTS *

test_utils/TestFile_WithErrors_DoNotFix.php

@@ -75,6 +75,19 @@ class TestClass
      */
     private boolean|string $bar;
 
+    private function testFunctionWithoutDocblock(): string {
+        // Function without a docblock, a required `@return` tag should NOT be added to
+        // the previous docblock ($bar) (should NOT be flagged).
+        return 'Hello World';
+    }
+
+    private function anotherFunctionWithoutDocblock(): int {
+        // Function without a docblock, a required `@return` tag should NOT be added to
+        // the previous docblock ($bar) (should NOT be flagged).
+        return 42;
+    }
+
+
 
     /***************
      * TYPES TESTS *

yCodeTech/Sniffs/Commenting/FunctionCommentSniff.php

@@ -65,6 +65,21 @@ public function process(File $phpcsFile, $stackPtr)
             return;
         }
 
+        // Check if this docblock actually belongs to this function
+        // There should be no other significant tokens between the docblock and the function
+        $tokenAfterComment = $phpcsFile->findNext(
+            [T_WHITESPACE, T_COMMENT, T_PUBLIC, T_PRIVATE, T_PROTECTED, T_STATIC, T_FINAL, T_ABSTRACT],
+            ($commentEnd + 1),
+            $stackPtr,
+            true
+        );
+        
+        if ($tokenAfterComment !== false && $tokenAfterComment !== $stackPtr) {
+            // There are other tokens between the docblock and the function,
+            // so this docblock doesn't belong to this function. So the function doesn't have a docblock, and found a previous function's docblock instead. Skipping.
+            return;
+        }
+
         $commentStart = $tokens[$commentEnd]['comment_opener'];
         // Check if function returns void
         $hasVoidReturn = $this->hasVoidReturn($phpcsFile, $stackPtr);