From 679621528cb60100954fb234c56080ca67074722 Mon Sep 17 00:00:00 2001
From: Choraimy Kroonstuiver <3661474+axlon@users.noreply.github.com>
Date: Mon, 21 Nov 2022 14:29:46 +0100
Subject: [PATCH] Fix `Squiz.Commenting.FunctionComment.InvalidNoReturn` false
 positive when return type is `never`

---
 .../Squiz/Sniffs/Commenting/FunctionCommentSniff.php     | 9 ++++++---
 .../Squiz/Tests/Commenting/FunctionCommentUnitTest.inc   | 5 +++++
 .../Tests/Commenting/FunctionCommentUnitTest.inc.fixed   | 5 +++++
 3 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/src/Standards/Squiz/Sniffs/Commenting/FunctionCommentSniff.php b/src/Standards/Squiz/Sniffs/Commenting/FunctionCommentSniff.php
index 38170d22e4..3c79a7a8c4 100644
--- a/src/Standards/Squiz/Sniffs/Commenting/FunctionCommentSniff.php
+++ b/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++) {
diff --git a/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc b/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc
index 55e0fe9bb9..a44f5e0e2e 100644
--- a/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc
+++ b/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() {}
diff --git a/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc.fixed b/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc.fixed
index 22474caf85..3d2e10fd6a 100644
--- a/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc.fixed
+++ b/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() {}