fix(ControllerMethod): Log an error if return statements are detected but no @return annotation is present

Signed-off-by: provokateurin <[email protected]>

Author: provokateurin

src/ControllerMethod.php

@@ -8,6 +8,7 @@
 namespace OpenAPIExtractor;
 
 use PhpParser\Node\Stmt\ClassMethod;
+use PhpParser\Node\Stmt\Return_;
 use PHPStan\PhpDocParser\Ast\PhpDoc\DeprecatedTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\GenericTagValueNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ParamTagValueNode;
@@ -45,7 +46,7 @@ public static function parse(string $context,
 		bool $isPasswordConfirmation,
 		bool $isCORS,
 	): ControllerMethod {
-		global $phpDocParser, $lexer, $allowMissingDocs;
+		global $phpDocParser, $lexer, $nodeFinder, $allowMissingDocs;
 
 		$parameters = [];
 		$responses = [];
@@ -56,6 +57,9 @@ public static function parse(string $context,
 		$methodParameters = $method->getParams();
 		$docParameters = [];
 
+		$returnStmtCount = count($nodeFinder->findInstanceOf($method->getStmts(), Return_::class));
+		$returnTagCount = 0;
+
 		$doc = $method->getDocComment()?->getText();
 		if ($doc !== null) {
 			$docNodes = $phpDocParser->parse(new TokenIterator($lexer->tokenize($doc)))->children;
@@ -109,6 +113,8 @@ public static function parse(string $context,
 					}
 
 					if ($docNode->value instanceof ReturnTagValueNode) {
+						$returnTagCount++;
+
 						$type = $docNode->value->type;
 
 						$responses = array_merge($responses, ResponseType::resolve($context . ': @return', $type));
@@ -136,6 +142,10 @@ public static function parse(string $context,
 			}
 		}
 
+		if ($returnStmtCount !== 0 && $returnTagCount === 0) {
+			Logger::error($context, 'Missing @return annotation');
+		}
+
 		if (!$allowMissingDocs) {
 			foreach (array_unique(array_map(fn (ControllerMethodResponse $response): int => $response->statusCode, array_filter($responses, fn (?ControllerMethodResponse $response): bool => $response != null))) as $statusCode) {
 				if ($statusCode < 500 && (!array_key_exists($statusCode, $responseDescriptions) || $responseDescriptions[$statusCode] === '')) {