Remove more specific PHPDoc @return from PHP 8.1 stubs

Author: ondrejmirtes

Diff for: extractor/extract.php

@@ -4,6 +4,7 @@
 use PhpParser\Comment;
 use PhpParser\Node;
 use PhpParser\ParserFactory;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocChildNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
@@ -475,6 +476,26 @@ private function compareFunctions(Node\FunctionLike $old, Node\FunctionLike $new
 			}
 		}
 
+		if (
+			$old->getReturnType() !== null
+			&& $new->getReturnType() !== null
+			&& $new->getDocComment() !== null
+		) {
+			if ($old->getDocComment() === null || $this->findPhpDocReturn($this->parseDocComment($old->getDocComment()->getText())) === null) {
+				$newPhpDocNode = $this->parseDocComment($new->getDocComment()->getText());
+				if ($this->findPhpDocReturn($newPhpDocNode) !== null) {
+					$newPhpDocNodeWithoutReturn = new PhpDocNode(array_values(array_filter($newPhpDocNode->children, function (PhpDocChildNode $child): bool {
+						if (!$child instanceof PhpDocTagNode) {
+							return true;
+						}
+
+						return !$child->value instanceof ReturnTagValueNode;
+					})));
+					$new->setDocComment(new Comment\Doc((string) $newPhpDocNodeWithoutReturn));
+				}
+			}
+		}
+
 		return [$new];
 	}