[DeadCode] Skip RemoveUselessReturnTagRector on BracketsAwareUnionTyp…

…eNode (#694)

* Add failing test fixture for RemoveUselessReturnTagRector

# Failing Test for RemoveUselessReturnTagRector

Based on https://getrector.org/demo/1ebfe6a8-4b08-6440-8cb6-8bfed0a3a869

* Closes #692

* handle array typed

* phpstan

* case by case to avoid unwanted behavior

Co-authored-by: Jáchym Toušek <enumag@gmail.com>

rules-tests/DeadCode/Rector/ClassMethod/RemoveUselessReturnTagRector/Fixture/skip_tag_with_generic_type.php.inc

@@ -0,0 +1,22 @@
+<?php
+
+namespace Rector\Tests\DeadCode\Rector\ClassMethod\RemoveUselessReturnTagRector\Fixture;
+
+use Ds\Vector;
+use IteratorAggregate;
+
+/**
+ * @template TValue
+ *
+ * @implements IteratorAggregate<int, TValue>
+ */
+final class ImmutableVector implements IteratorAggregate
+{
+    /**
+     * @return iterable<TValue>|null
+     */
+    public function getVector(): ?iterable
+    {
+    }
+}
+?>

rules/DeadCode/PhpDoc/DeadReturnTagValueNodeAnalyzer.php

@@ -7,6 +7,8 @@
 use PhpParser\Node\FunctionLike;
 use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
 use PHPStan\PhpDocParser\Ast\Type\GenericTypeNode;
+use PHPStan\PhpDocParser\Ast\Type\IdentifierTypeNode;
+use Rector\BetterPhpDocParser\ValueObject\Type\BracketsAwareUnionTypeNode;
 use Rector\BetterPhpDocParser\ValueObject\Type\SpacingAwareCallableTypeNode;
 use Rector\NodeTypeResolver\TypeComparator\TypeComparator;
 
@@ -32,14 +34,38 @@ public function isDead(ReturnTagValueNode $returnTagValueNode, FunctionLike $fun
             return false;
         }
 
-        if ($returnTagValueNode->type instanceof GenericTypeNode) {
+        if (in_array($returnTagValueNode->type::class, [
+            GenericTypeNode::class,
+            SpacingAwareCallableTypeNode::class,
+        ], true)) {
             return false;
         }
 
-        if ($returnTagValueNode->type instanceof SpacingAwareCallableTypeNode) {
-            return false;
+        if (! $returnTagValueNode->type instanceof BracketsAwareUnionTypeNode) {
+            return $returnTagValueNode->description === '';
+        }
+
+        if (! $this->hasGenericType($returnTagValueNode->type)) {
+            return $returnTagValueNode->description === '';
+        }
+
+        return false;
+    }
+
+    private function hasGenericType(BracketsAwareUnionTypeNode $bracketsAwareUnionTypeNode): bool
+    {
+        $types = $bracketsAwareUnionTypeNode->types;
+
+        foreach ($types as $type) {
+            if ($type instanceof GenericTypeNode) {
+                if ($type->type instanceof IdentifierTypeNode && $type->type->name === 'array') {
+                    continue;
+                }
+
+                return true;
+            }
         }
 
-        return $returnTagValueNode->description === '';
+        return false;
     }
 }