Squiz/NonExecutableCode: make sniff more code style independent

When determining whether a `return` statement is the last code token in a function body, comments should be ignored, but weren't.

Fixed now. Includes tests.

Author: jrfnl

CHANGELOG.md

@@ -175,6 +175,8 @@ The file documents changes to the PHP_CodeSniffer project.
     - Thanks to @simonsan for the patch
 - Fixed bug #3893 : Generic/DocComment : the SpacingAfterTagGroup fixer could accidentally remove ignore annotations
     - Thanks to Juliette Reinders Folmer (@jrfnl) for the patch
+- Fixed bug #3898 : Squiz/NonExecutableCode : the sniff could get confused over comments in unexpected places
+    - Thanks to Juliette Reinders Folmer (@jrfnl) for the patch
 - Fixed bug #3904 : Squiz/FunctionSpacing : prevent potential fixer conflict
     - Thanks to Juliette Reinders Folmer (@jrfnl) for the patch
 - Fixed bug #3906 : Tokenizer/CSS: fixed a bug related to the unsupported slash comment syntax

src/Standards/Squiz/Sniffs/PHP/NonExecutableCodeSniff.php

@@ -114,9 +114,9 @@ public function process(File $phpcsFile, $stackPtr)
         }
 
         if ($tokens[$stackPtr]['code'] === T_RETURN) {
-            $next = $phpcsFile->findNext(T_WHITESPACE, ($stackPtr + 1), null, true);
+            $next = $phpcsFile->findNext(Tokens::$emptyTokens, ($stackPtr + 1), null, true);
             if ($tokens[$next]['code'] === T_SEMICOLON) {
-                $next = $phpcsFile->findNext(T_WHITESPACE, ($next + 1), null, true);
+                $next = $phpcsFile->findNext(Tokens::$emptyTokens, ($next + 1), null, true);
                 if ($tokens[$next]['code'] === T_CLOSE_CURLY_BRACKET) {
                     // If this is the closing brace of a function
                     // then this return statement doesn't return anything

src/Standards/Squiz/Tests/PHP/NonExecutableCodeUnitTest.1.inc

@@ -396,5 +396,22 @@ function executionStoppingThrowExpressionsE() {
     echo 'non-executable';
 }
 
+function returnNotRequiredIgnoreCommentsA()
+{
+    if ($something === TRUE) {
+        return /*comment*/;
+    }
+
+    echo 'foo';
+    return /*comment*/;
+}
+
+function returnNotRequiredIgnoreCommentsB()
+{
+    echo 'foo';
+    return;
+    /*comment*/
+}
+
 // Intentional syntax error.
 return array_map(

src/Standards/Squiz/Tests/PHP/NonExecutableCodeUnitTest.php

@@ -82,6 +82,8 @@ public function getWarningList($testFile='')
                 386 => 1,
                 391 => 1,
                 396 => 1,
+                406 => 1,
+                412 => 1,
             ];
 
         case 'NonExecutableCodeUnitTest.2.inc':