Merge pull request #18 from KentarouTakeda/fix-generics-and-closures-return-type

Fixed incorrect parsing of return types for generics and closures

phpunit.xml.dist

@@ -1,14 +1,13 @@
 <?xml version="1.0" encoding="utf-8"?>
-
-<phpunit colors="true" strict="true" bootstrap="vendor/autoload.php">
+<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" colors="true" bootstrap="vendor/autoload.php" xsi:noNamespaceSchemaLocation="https://schema.phpunit.de/9.3/phpunit.xsd">
+  <coverage>
+    <include>
+      <directory suffix=".php">./src/</directory>
+    </include>
+  </coverage>
   <testsuites>
     <testsuite name="phpDocumentor\Reflection\DocBlock">
       <directory>./tests/</directory>
     </testsuite>
   </testsuites>
-  <filter>
-    <whitelist>
-        <directory suffix=".php">./src/</directory>
-    </whitelist>
-  </filter>
 </phpunit>

src/Barryvdh/Reflection/DocBlock/Description.php

@@ -109,7 +109,7 @@ class Description implements \Reflector
                     )
                 \}/Sux',
                 $this->contents,
-                null,
+                -1,
                 PREG_SPLIT_DELIM_CAPTURE
             );
 

src/Barryvdh/Reflection/DocBlock/Tag.php

@@ -95,7 +95,9 @@ class Tag implements \Reflector
         'var'
             => '\Barryvdh\Reflection\DocBlock\Tag\VarTag',
         'version'
-            => '\Barryvdh\Reflection\DocBlock\Tag\VersionTag'
+            => '\Barryvdh\Reflection\DocBlock\Tag\VersionTag',
+        'SuppressWarnings'
+            => '\Barryvdh\Reflection\DocBlock\Tag\SuppressWarningsTag'
     );
 
     /**

src/Barryvdh/Reflection/DocBlock/Tag/MethodTag.php

@@ -80,10 +80,12 @@ class MethodTag extends ReturnTag
                         (?:[\w\|_\\\\]*\$this[\w\|_\\\\]*)
                         |
                         (?:
-                            (?:[\w\|_\\\\]+)
+                            (?:[\w\|_\\\\]+(?:<[\s\S]*>)?)
                             # array notation
                             (?:\[\])*
                         )*
+                        |
+                        (?:\([\s\S]*\))?
                     )
                     \s+
                 )?

src/Barryvdh/Reflection/DocBlock/Tag/ParamTag.php

@@ -46,12 +46,37 @@ class ParamTag extends ReturnTag
     public function setContent($content)
     {
         Tag::setContent($content);
-        $parts = preg_split(
-            '/(\s+)/Su',
-            $this->description,
-            3,
-            PREG_SPLIT_DELIM_CAPTURE
-        );
+
+        $parts = [];
+        $rest = $this->description;
+
+        // parsing generics and closures to detect types
+        for($pos = 0, $stacks = []; $pos < strlen($rest); $pos++) {
+            $char = $rest[$pos];
+
+            if($char === '<') {
+                array_unshift($stacks, $char);
+            }
+            if($char === '(') {
+                array_unshift($stacks, $char);
+            }
+            if($char === '>' && isset($stacks[0]) && $stacks[0] === '<') {
+                array_shift($stacks);
+            }
+            if($char === ')' && isset($stacks[0]) && $stacks[0] === '(') {
+                array_shift($stacks);
+            }
+
+            if(!$stacks && preg_match('/\A(\s+)(.*)/su', substr($rest, $pos), $matches)) {
+                $parts[0] = substr($rest, 0, $pos);
+                $parts[1] = $matches[1];
+                $rest = $matches[2];
+
+                break;
+            }
+        }
+
+        array_push($parts, ...preg_split('/(\s+)/u', $rest, 2, PREG_SPLIT_DELIM_CAPTURE));
 
         // if the first item that is encountered is not a variable; it is a type
         if (isset($parts[0])

src/Barryvdh/Reflection/DocBlock/Tag/SuppressWarningsTag.php

@@ -0,0 +1,30 @@
+<?php
+/**
+ * phpDocumentor
+ *
+ * PHP Version 5.3
+ *
+ * @author    Andrew Smith <[email protected]>
+ * @copyright 2010-2011 Mike van Riel / Naenius (http://www.naenius.com)
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      http://phpdoc.org
+ */
+
+namespace Barryvdh\Reflection\DocBlock\Tag;
+
+use Barryvdh\Reflection\DocBlock\Tag;
+
+/**
+ * Reflection class for a @SuppressWarnings tag in a Docblock.
+ *
+ * @author  Andrew Smith <[email protected]>
+ * @license http://www.opensource.org/licenses/mit-license.php MIT
+ * @link    http://phpdoc.org
+ */
+class SuppressWarningsTag extends Tag
+{
+    public function __toString()
+    {
+        return "@{$this->getName()}{$this->getContent()}";
+    }
+}

src/Barryvdh/Reflection/DocBlock/Type/Collection.php

@@ -145,9 +145,9 @@ class Collection extends \ArrayObject
                 $type_parts[] = $curr_type;
                 $curr_type = '';
             } else {
-                if ($char === '<') {
+                if ($char === '<' || $char === '(') {
                     $nest_level++;
-                } else if ($char === '>') {
+                } else if ($char === '>' || $char === ')') {
                     $nest_level--;
                 }
 
@@ -189,6 +189,10 @@ class Collection extends \ArrayObject
             return $type;
         }
 
+        if($type[0] === '(') {
+            return $type;
+        }
+
         if ($this->isTypeAnArray($type)) {
             return $this->expand(substr($type, 0, -2)) . self::OPERATOR_ARRAY;
         }

tests/Barryvdh/Reflection/DocBlock/Tag/MethodTagTest.php

@@ -142,7 +142,25 @@ class MethodTagTest extends TestCase
             array(
                 'static static foo()',
                 true, 'foo', 'static', true, 0, ''
-            )
+            ),
+
+            // generic array
+            array(
+                'array<int, string> foo()',
+                true, 'foo', 'array<int, string>', false, 0, ''
+            ),
+
+            // nested generics
+            array(
+                'array<int, array<string, mixed>> foo()',
+                true, 'foo', 'array<int, array<string, mixed>>', false, 0, ''
+            ),
+
+            // closure
+            array(
+                '(\Closure(int, string): bool) foo()',
+                true, 'foo', '(\Closure(int, string): bool)', false, 0, ''
+            ),
         );
     }
 }

tests/Barryvdh/Reflection/DocBlock/Tag/ParamTagTest.php

@@ -114,7 +114,75 @@ class ParamTagTest extends TestCase
                 array('int'),
                 '$bob',
                 "Type on a new line"
-            )
+            ),
+
+            // generic array
+            array(
+                'param',
+                'array<int, string> $names',
+                'array<int, string>',
+                array('array<int, string>'),
+                '$names',
+                ''
+            ),
+
+            // nested generics
+            array(
+                'param',
+                'array<int, array<string, mixed>> $arrays',
+                'array<int, array<string, mixed>>',
+                array('array<int, array<string, mixed>>'),
+                '$arrays',
+                ''
+            ),
+
+            // closure
+            array(
+                'param',
+                '(\Closure(int, string): bool) $callback',
+                '(\Closure(int, string): bool)',
+                array('(\Closure(int, string): bool)'),
+                '$callback',
+                ''
+            ),
+
+            // generic array in closure
+            array(
+                'param',
+                '(\Closure(array<int, string>): bool) $callback',
+                '(\Closure(array<int, string>): bool)',
+                array('(\Closure(array<int, string>): bool)'),
+                '$callback',
+                ''
+            ),
+
+            // union types in closure
+            array(
+                'param',
+                '(\Closure(int|string): bool)|bool $callback',
+                '(\Closure(int|string): bool)|bool',
+                array('(\Closure(int|string): bool)', 'bool'),
+                '$callback',
+                ''
+            ),
+
+            // example from Laravel Framework - Eloquent Builder)
+            array(
+                'param',
+                'array<array-key, array|(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)|string>|string  $relations',
+                'array<array-key, array|(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)|string>|string',
+                array('array<array-key, array|(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)|string>', 'string'),
+                '$relations',
+                ''
+            ),
+            array(
+                'param',
+                '(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)|string|null  $callback',
+                '(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)|string|null',
+                array('(\Closure(\Illuminate\Database\Eloquent\Relations\Relation<*,*,*>): mixed)', 'string', 'null'),
+                '$callback',
+                ''
+            ),
         );
     }
 }

tests/Barryvdh/Reflection/DocBlock/Tag/SuppressWarningsTagTest.php

@@ -0,0 +1,75 @@
+<?php
+/**
+ * phpDocumentor SuppressWarnings Tag Test
+ *
+ * PHP version 5.3
+ *
+ * @author    Andrew Smith <[email protected]>
+ * @copyright 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com)
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      http://phpdoc.org
+ */
+
+namespace Barryvdh\Reflection\DocBlock\Tag;
+
+use PHPUnit\Framework\Test;
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Test class for \Barryvdh\Reflection\DocBlock\Tag\SuppressWarningsTag
+ *
+ * @author    Andrew Smith <[email protected]>
+ * @copyright 2010-2011 Mike van Riel / Naenius. (http://www.naenius.com)
+ * @license   http://www.opensource.org/licenses/mit-license.php MIT
+ * @link      http://phpdoc.org
+ */
+class SuppressWarningsTagTest extends TestCase
+{
+    /**
+     * Test that the \Barryvdh\Reflection\DocBlock\Tag\SuppressWarningsTag can
+     * understand the @SuppressWarnings doc block.
+     *
+     * @param string $type
+     * @param string $content
+     * @param string $exType
+     * @param string $exVariable
+     * @param string $exDescription
+     *
+     * @covers \Barryvdh\Reflection\DocBlock\Tag\SuppressWarningsTag
+     * @dataProvider provideDataForConstuctor
+     *
+     * @return void
+     */
+    public function testConstructorParesInputsIntoCorrectFields(
+        $type,
+        $content,
+        $description
+    ) {
+        $tag = new SuppressWarningsTag($type, $content);
+
+        $this->assertEquals($type, $tag->getName());
+        $this->assertEquals($description, $tag->getDescription());
+    }
+
+    /**
+     * Data provider for testConstructorParesInputsIntoCorrectFields
+     *
+     * @return array
+     */
+    public function provideDataForConstuctor()
+    {
+        // $type, $content, $description
+        return array(
+            array(
+                'SuppressWarnings',
+                'SuppressWarnings(PHPMD)',
+                'SuppressWarnings(PHPMD)',
+            ),
+            array(
+                'SuppressWarnings',
+                'SuppressWarnings(PHPMD.TooManyMethods)',
+                'SuppressWarnings(PHPMD.TooManyMethods)',
+            ),
+        );
+    }
+}