Best way to document (phpdoc) generators (methods that yield)

Question

What is the best way to document, for phpdocumentor2, a method that is a generator.

I don't think @return really works for yield, but I can't seem to find any proper alternative.

Is it just a matter of waiting for phpdoc to catch up?

Answer 1

I went with @return Generator|SomeObject[], where SomeObject is the thing being yielded.

PhpStorm handles this well too, as it now normally hints Generator methods and when iterated it hints SomeObject methods.

(Still, I would prefer a native @yield.)

Answer 2

From the PHP Manual:

When a generator function is called for the first time, an object of the internal Generator class is returned.

So strictly speaking, @return Generator would be correct, although not super descriptive of what you can expect to get back when you iterate over the generator.