Add return tag factory

src/DocBlock/Tags/Factory/ReturnFactory.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace phpDocumentor\Reflection\DocBlock\Tags\Factory;
+
+use phpDocumentor\Reflection\DocBlock\DescriptionFactory;
+use phpDocumentor\Reflection\DocBlock\Tag;
+use phpDocumentor\Reflection\DocBlock\Tags\Return_;
+use phpDocumentor\Reflection\Types\Context;
+use PHPStan\PhpDocParser\Ast\PhpDoc\PhpDocTagNode;
+use PHPStan\PhpDocParser\Ast\PhpDoc\ReturnTagValueNode;
+use Webmozart\Assert\Assert;
+
+/**
+ * @internal This class is not part of the BC promise of this library.
+ */
+final class ReturnFactory implements PHPStanFactory
+{
+    private TypeFactory $typeFactory;
+    private DescriptionFactory $descriptionFactory;
+
+    public function __construct(TypeFactory $typeFactory, DescriptionFactory $descriptionFactory)
+    {
+        $this->typeFactory = $typeFactory;
+        $this->descriptionFactory = $descriptionFactory;
+    }
+
+    public function create(PhpDocTagNode $node, ?Context $context): Tag
+    {
+        $tagValue = $node->value;
+        Assert::isInstanceOf($tagValue, ReturnTagValueNode::class);
+
+        return new Return_(
+            $this->typeFactory->createType($tagValue->type, $context),
+            $this->descriptionFactory->create($tagValue->description, $context)
+        );
+    }
+
+    public function supports(PhpDocTagNode $node, ?Context $context): bool
+    {
+        return $node->value instanceof ReturnTagValueNode;
+    }
+}

src/DocBlock/Tags/Factory/TypeFactory.php

@@ -36,6 +36,7 @@ use PHPStan\PhpDocParser\Ast\Type\ThisTypeNode;
 use PHPStan\PhpDocParser\Ast\Type\TypeNode;
 use PHPStan\PhpDocParser\Ast\Type\UnionTypeNode;
 
+use function array_filter;
 use function array_map;
 use function array_reverse;
 use function get_class;
@@ -78,6 +79,7 @@ final class TypeFactory
 
             case ConstTypeNode::class:
                 return null;
+
             case GenericTypeNode::class:
                 return $this->createFromGeneric($type, $context);
 

src/DocBlock/Tags/Method.php

@@ -31,9 +31,12 @@ use function preg_match;
 use function sort;
 use function strpos;
 use function substr;
+use function trigger_error;
 use function trim;
 use function var_export;
 
+use const E_USER_DEPRECATED;
+
 /**
  * Reflection class for an {@}method in a Docblock.
  */

src/DocBlock/Tags/Param.php

@@ -26,7 +26,9 @@ use function array_unshift;
 use function implode;
 use function strpos;
 use function substr;
+use function trigger_error;
 
+use const E_USER_DEPRECATED;
 use const PREG_SPLIT_DELIM_CAPTURE;
 
 /**

src/DocBlock/Tags/Property.php

@@ -26,7 +26,9 @@ use function array_unshift;
 use function implode;
 use function strpos;
 use function substr;
+use function trigger_error;
 
+use const E_USER_DEPRECATED;
 use const PREG_SPLIT_DELIM_CAPTURE;
 
 /**

src/DocBlock/Tags/PropertyRead.php

@@ -26,7 +26,9 @@ use function array_unshift;
 use function implode;
 use function strpos;
 use function substr;
+use function trigger_error;
 
+use const E_USER_DEPRECATED;
 use const PREG_SPLIT_DELIM_CAPTURE;
 
 /**

src/DocBlock/Tags/PropertyWrite.php

@@ -26,7 +26,9 @@ use function array_unshift;
 use function implode;
 use function strpos;
 use function substr;
+use function trigger_error;
 
+use const E_USER_DEPRECATED;
 use const PREG_SPLIT_DELIM_CAPTURE;
 
 /**

src/DocBlock/Tags/Return_.php

@@ -20,6 +20,10 @@ use phpDocumentor\Reflection\TypeResolver;
 use phpDocumentor\Reflection\Types\Context as TypeContext;
 use Webmozart\Assert\Assert;
 
+use function trigger_error;
+
+use const E_USER_DEPRECATED;
+
 /**
  * Reflection class for a {@}return tag in a Docblock.
  */

src/DocBlock/Tags/Var_.php

@@ -26,7 +26,9 @@ use function array_unshift;
 use function implode;
 use function strpos;
 use function substr;
+use function trigger_error;
 
+use const E_USER_DEPRECATED;
 use const PREG_SPLIT_DELIM_CAPTURE;
 
 /**

src/DocBlockFactory.php

@@ -22,7 +22,9 @@ use phpDocumentor\Reflection\DocBlock\TagFactory;
 use phpDocumentor\Reflection\DocBlock\Tags\Factory\AbstractPHPStanFactory;
 use phpDocumentor\Reflection\DocBlock\Tags\Factory\Factory;
 use phpDocumentor\Reflection\DocBlock\Tags\Factory\ParamFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\ReturnFactory;
 use phpDocumentor\Reflection\DocBlock\Tags\Factory\TypeFactory;
+use phpDocumentor\Reflection\DocBlock\Tags\Factory\VarFactory;
 use Webmozart\Assert\Assert;
 
 use function array_shift;
@@ -68,13 +70,16 @@ final class DocBlockFactory implements DocBlockFactoryInterface
         $typeFactory = new TypeFactory($typeResolver);
 
         $phpstanTagFactory = new AbstractPHPStanFactory(
-            new ParamFactory($typeFactory, $descriptionFactory)
+            new ParamFactory($typeFactory, $descriptionFactory),
+            new VarFactory($typeFactory, $descriptionFactory),
+            new ReturnFactory($typeFactory, $descriptionFactory),
         );
 
         $tagFactory->addService($descriptionFactory);
         $tagFactory->addService($typeResolver);
         $tagFactory->registerTagHandler('param', $phpstanTagFactory);
         $tagFactory->registerTagHandler('var', $phpstanTagFactory);
+        $tagFactory->registerTagHandler('return', $phpstanTagFactory);
 
         $docBlockFactory = new self($descriptionFactory, $tagFactory);
         foreach ($additionalTags as $tagName => $tagHandler) {

src/PseudoTypes/ArrayShapeItem.php

@@ -5,8 +5,8 @@ declare(strict_types=1);
 namespace phpDocumentor\Reflection\PseudoTypes;
 
 use phpDocumentor\Reflection\Type;
-
 use phpDocumentor\Reflection\Types\Mixed_;
+
 use function sprintf;
 
 final class ArrayShapeItem

tests/unit/DocBlock/Tags/Factory/ReturnFactoryTest.php

@@ -0,0 +1,43 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link      http://phpdoc.org
+ */
+
+namespace phpDocumentor\Reflection\DocBlock\Tags\Factory;
+
+use phpDocumentor\Reflection\DocBlock\Description;
+use phpDocumentor\Reflection\DocBlock\Tags\Return_;
+use phpDocumentor\Reflection\Types\Context;
+use phpDocumentor\Reflection\Types\String_;
+
+final class ReturnFactoryTest extends TagFactoryTestCase
+{
+    /**
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\Factory\ParamFactory::__construct
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\Factory\ParamFactory::create
+     * @covers \phpDocumentor\Reflection\DocBlock\Tags\Factory\ParamFactory::supports
+     */
+    public function testParamIsCreated(): void
+    {
+        $ast = $this->parseTag('@return string');
+        $factory = new ReturnFactory($this->giveTypeFactory(), $this->givenDescriptionFactory());
+        $context = new Context('global');
+
+        self::assertTrue($factory->supports($ast, $context));
+        self::assertEquals(
+            new Return_(
+                new String_(),
+                new Description('')
+            ),
+            $factory->create($ast, $context)
+        );
+    }
+}