diff --git a/src/NodeVisitor/GeneratorDetector.php b/src/NodeVisitor/GeneratorDetector.php index 906daa4..7d13394 100644 --- a/src/NodeVisitor/GeneratorDetector.php +++ b/src/NodeVisitor/GeneratorDetector.php @@ -23,7 +23,12 @@ class GeneratorDetector extends NodeVisitorAbstract private bool $isGenerator = false; /** - * {@inheritDoc} + * Detects yield expressions, without looking into closures + * + * The return type is declared in the docblock only, like in PhpParser\NodeVisitor: an explicit @return keeps + * Symfony's DebugClassLoader from reporting the tentative return type of the parent method. + * + * @return int|null self::DONT_TRAVERSE_CHILDREN for closures, null otherwise */ public function enterNode(Node $node) { diff --git a/src/NodeVisitor/RootNamespaceNormalizer.php b/src/NodeVisitor/RootNamespaceNormalizer.php index b412065..3280011 100644 --- a/src/NodeVisitor/RootNamespaceNormalizer.php +++ b/src/NodeVisitor/RootNamespaceNormalizer.php @@ -25,7 +25,14 @@ class RootNamespaceNormalizer extends NodeVisitorAbstract { /** - * {@inheritdoc} + * Wraps the statements of a file without a namespace into a global namespace node + * + * The return type is declared in the docblock only, like in PhpParser\NodeVisitor: an explicit @return keeps + * Symfony's DebugClassLoader from reporting the tentative return type of the parent method. + * + * @param \PhpParser\Node[] $nodes + * + * @return \PhpParser\Node[]|null Null when the file declares namespaces itself */ public function beforeTraverse(array $nodes) { diff --git a/src/NodeVisitor/StaticVariablesCollector.php b/src/NodeVisitor/StaticVariablesCollector.php index 2e01588..f218f06 100644 --- a/src/NodeVisitor/StaticVariablesCollector.php +++ b/src/NodeVisitor/StaticVariablesCollector.php @@ -45,7 +45,12 @@ public function __construct(\ReflectionClass|\ReflectionFunction|\ReflectionMeth } /** - * {@inheritDoc} + * Collects static variables with their default values, without looking into closures + * + * The return type is declared in the docblock only, like in PhpParser\NodeVisitor: an explicit @return keeps + * Symfony's DebugClassLoader from reporting the tentative return type of the parent method. + * + * @return int|null self::DONT_TRAVERSE_CHILDREN for closures, null otherwise */ public function enterNode(Node $node) { diff --git a/tests/NodeVisitor/NodeVisitorReturnTypeTest.php b/tests/NodeVisitor/NodeVisitorReturnTypeTest.php new file mode 100644 index 0000000..edb087d --- /dev/null +++ b/tests/NodeVisitor/NodeVisitorReturnTypeTest.php @@ -0,0 +1,64 @@ + + * + * This source file is subject to the license that is bundled + * with this source code in the file LICENSE. + */ + +namespace Go\ParserReflection\NodeVisitor; + +use PhpParser\NodeVisitor; +use PHPUnit\Framework\Attributes\DataProvider; +use PHPUnit\Framework\TestCase; +use ReflectionClass; + +/** + * PhpParser\NodeVisitor declares the return types of its methods in docblocks only. An implementation without a + * native return type and without its own @return makes Symfony's DebugClassLoader report that the parent "might + * add" a native return type, so every overridden visitor method documents its return type explicitly. + */ +final class NodeVisitorReturnTypeTest extends TestCase +{ + /** + * @param class-string $visitorClass + */ + #[DataProvider('visitorMethods')] + public function testOverriddenVisitorMethodsDocumentTheirReturnType(string $visitorClass, string $methodName): void + { + $method = new ReflectionClass($visitorClass)->getMethod($methodName); + $this->assertFalse($method->hasReturnType(), 'The return type is documented, not declared: PhpParser\NodeVisitor owns it'); + + $docComment = $method->getDocComment(); + $this->assertIsString($docComment); + $this->assertMatchesRegularExpression('/@return\s+\S+/', $docComment); + } + + /** + * @return iterable, string}> + */ + public static function visitorMethods(): iterable + { + $visitorMethods = array_map( + static fn (\ReflectionMethod $method): string => $method->getName(), + new ReflectionClass(NodeVisitor::class)->getMethods() + ); + foreach (glob(dirname(__DIR__, 2) . '/src/NodeVisitor/*.php') ?: [] as $file) { + /** @var class-string $visitorClass */ + $visitorClass = __NAMESPACE__ . '\\' . basename($file, '.php'); + $visitor = new ReflectionClass($visitorClass); + if (!$visitor->implementsInterface(NodeVisitor::class)) { + continue; + } + foreach ($visitorMethods as $methodName) { + if ($visitor->getMethod($methodName)->getDeclaringClass()->getName() === $visitorClass) { + yield $visitor->getShortName() . '::' . $methodName => [$visitorClass, $methodName]; + } + } + } + } +}