Allow using the Type attribute to specify the return type of a function or method

Author: carlos-granados

README.md

@@ -90,13 +90,13 @@ And then install any needed extensions/plugins for the tools that you use.
 
 ## List of implemented attributes
 
-These are the available attributes and their corresponding PHPDoc annotation:
-
-| Attribute | PHPDoc Annotation |
-|---|-------------------|
-| [IsReadOnly](doc/IsReadOnly.md)  | `@readonly`       |
-| [Param](doc/Param.md) | `@param`          |
-| [Returns](doc/Returns.md) | `@return`         |
-| [Template](doc/Template.md) | `@template`       |
-| [Type](doc/Type.md) | `@var`            |
+These are the available attributes and their corresponding PHPDoc annotations:
+
+| Attribute | PHPDoc Annotations |
+|---|--------------------|
+| [IsReadOnly](doc/IsReadOnly.md)  | `@readonly`        |
+| [Param](doc/Param.md) | `@param`           |
+| [Returns](doc/Returns.md) | `@return`          |
+| [Template](doc/Template.md) | `@template`        |
+| [Type](doc/Type.md) | `@var` `@return`   |
 

doc/Returns.md

@@ -4,6 +4,8 @@ This attribute is the equivalent of the `@return` annotation. It can be used on
 
 We could not use `Return` for the name of this attribute because `return` is a reserved word in PHP.
 
+Instead of using this attribute, you can also use the `Type` aatribute which provides equivalent functionality.
+
 ## Arguments
 
 The attribute accepts a string which describes the type of the value returned by the function or method. The attribute itself does not have a knowledge of which types are valid and which are not and this will depend on the implementation for each particular tool.
@@ -22,7 +24,7 @@ class ReturnsExample
     #[Returns('Array<string>')]
     public function getNames(): array
     {
-        ...
+        return ['Fred', 'John'];
     }    
 }
 ```

doc/Type.md

@@ -1,12 +1,14 @@
 # `Type` Attribute
 
-This attribute is the equivalent of the `@var` annotation *when used for class properties or class constants*.
+This attribute is the equivalent of the `@var` annotation *when used for class properties or class constants* and is used to specify the type of this property or constant.
 
 We could not use `Var` for the name of this attribute because `var` is a reserved word in PHP. By using `Type` we emphasize that this attribute is used to declare the type of a class property or constant.
 
+This attribute can also be used instead of using the `Returns` attribute to specify the type of the return value of a function or method, replacing the `@return` annotation.
+
 ## Arguments
 
-The attribute accepts a string which describes the type of the class property or constant. The attribute itself does not have a knowledge of which types are valid and which are not and this will depend on the implementation for each particular tool.
+The attribute accepts a string which describes the type of the class property, constant or return value. The attribute itself does not have a knowledge of which types are valid and which are not and this will depend on the implementation for each particular tool.
 
 We expect that the attribute will be able to accept both basic types like `string` or `array` and more advanced types like `array<string>` or `Collection<int>`. We aim to accept all the types accepted by static analysis tools for the `@var` annotation.
 
@@ -24,7 +26,12 @@ class TypeExample
 
     #[Type('Array<int>')]
     private array $nums;
-    
+
+    #[Type('Array<int>')]
+    private function returnsArray()
+    {
+        return [1];
+    }    
     ...
 }
 ```

src/Type.php

@@ -8,7 +8,9 @@
 
 #[Attribute(
     Attribute::TARGET_CLASS_CONSTANT |
-    Attribute::TARGET_PROPERTY
+    Attribute::TARGET_PROPERTY |
+    Attribute::TARGET_METHOD |
+    Attribute::TARGET_FUNCTION
 )]
 final class Type
 {

tests/TypeTest.php

@@ -60,6 +60,16 @@ public function testMultiplePropertyTypes(): void
         $this->assertTrue($errorThrown);
     }
 
+    public function testMethodType(): void
+    {
+        $this->assertEquals('string', $this->methodType());
+    }
+
+    public function testFunctionType(): void
+    {
+        $this->assertEquals('string', functionType());
+    }
+
     private function propertyType(): string
     {
         return $this->getType('property');
@@ -85,9 +95,27 @@ private function multiplePropertyTypes(): string
         return $this->getType('propertyWithMultipleTypes');
     }
 
+    #[Type('string')]
+    private function methodType(): string
+    {
+        return $this->getMethodType(__FUNCTION__);
+    }
+
     private function getType(string $propertyName): string
     {
         $reflection = new ReflectionProperty($this, $propertyName);
+        return self::getTypeFromReflection($reflection);
+    }
+
+    private function getMethodType(string $methodName): string
+    {
+        $reflection = new ReflectionMethod($this, $methodName);
+        return self::getTypeFromReflection($reflection);
+    }
+
+    public static function getTypeFromReflection(
+        ReflectionProperty | ReflectionMethod | ReflectionFunction $reflection
+    ): string {
         $attributes = $reflection->getAttributes();
         $type = '';
         foreach ($attributes as $attribute) {
@@ -100,3 +128,10 @@ private function getType(string $propertyName): string
         return $type;
     }
 }
+
+#[Type('string')]
+function functionType(): string
+{
+    $reflection = new ReflectionFunction(__FUNCTION__);
+    return TypeTest::getTypeFromReflection($reflection);
+}