Document return type of Iterator::accept() so that Symfony's DebugClassLoader does not trigger a deprecation warning

[lyrixx]

see jolicode/JoliTypo#72 (comment)

[sebastianbergmann]

A missing @return bool annotation in a comment does not (and cannot) trigger a PHP deprecation.

[nicolas-grekas]

I can shed some light on the topic:

In order to help the community with adding return types, Symfony's DebugClassLoader triggers a deprecation when a child class doesn't declare a return type while a parent class/interface does.

Because we want this deprecation to be triggered to projects that run on PHP 7, this works by reading @return annotations.
This cannot rely on #[\ReturnTypeWillChange] because 1. attributes require PHP >= 8 and 2. #[\ReturnTypeWillChange] doesn't say what the tentative return type is for userland classes.

This works basically the same as #[\ReturnTypeWillChange], and it's not by mistake since I heavily contributed to the discussion that led to the attribute.

The TL;DR is: when #[\ReturnTypeWillChange] is used, it should also contain an @return annotation that tells the tentative type.

[sebastianbergmann]

Thank you for the explanation, Nicolas. But should Symfony's DebugClassLoader not limit itself to code it is responsible for?

[nicolas-grekas]

Symfony's DebugClassLoader is a generic tool that ppl can use to help move to native return types in a smooth way. There is no boundary that would define the code it is responsible for. We enable it by default in Symfony 5.4 because we figured out that's the best way to encourage everybody to adopt native return types (starting with userland apps first.)

@wouterj wrote a nice article about the process at https://wouterj.nl/2021/09/symfony-6-native-typing if you want to have a look (the article targets end users but the tool is also designed to help lib authors.)

DebugClassLoader as been designed to make this a win situation for everybody: if a codebase makes its return types super clear, then interpreting said codebase become very easy, and DebugClassLoader is able to make the most out of it, as could any other static/runtime analyzer.

Without the annotation, one has to either run the code on PHP 8.1 and use the getTentativeType(), or use some stub that duplicates the info. This PR makes it obvious what the return type is going to be, using local-only knowledge. If this is considered as an improvement (I do), then adding this annotation is worth it on its own. No need to mention DebugClassLoader to justify the change (but it's still nice to know there are nice practical corollaries to such a PR) :)