Merge pull request #3717 from axlon/invalid-return-never

Fix `Squiz.Commenting.FunctionComment.InvalidNoReturn` false positive when return type is `never`

Author: jrfnl

src/Standards/Squiz/Sniffs/Commenting/FunctionCommentSniff.php

@@ -143,9 +143,12 @@ protected function processReturn(File $phpcsFile, $stackPtr, $commentStart)
                             }
                         }
                     }//end if
-                } else if ($returnType !== 'mixed' && in_array('void', $typeNames, true) === false) {
-                    // If return type is not void, there needs to be a return statement
-                    // somewhere in the function that returns something.
+                } else if ($returnType !== 'mixed'
+                    && $returnType !== 'never'
+                    && in_array('void', $typeNames, true) === false
+                ) {
+                    // If return type is not void, never, or mixed, there needs to be a
+                    // return statement somewhere in the function that returns something.
                     if (isset($tokens[$stackPtr]['scope_closer']) === true) {
                         $endToken = $tokens[$stackPtr]['scope_closer'];
                         for ($returnToken = $stackPtr; $returnToken < $endToken; $returnToken++) {

src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc

@@ -1129,3 +1129,8 @@ public function variableCaseTest(
 public function variableOrderMismatch($bar, $baz, $foo) {
     return;
 }
+
+/**
+ * @return never
+ */
+function foo() {}

src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc.fixed

@@ -1129,3 +1129,8 @@ public function variableCaseTest(
 public function variableOrderMismatch($bar, $baz, $foo) {
     return;
 }
+
+/**
+ * @return never
+ */
+function foo() {}