Home » Php » php – Best way to document (phpdoc) generators (methods that yield)

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

Posted by: admin April 23, 2020 Leave a comment

Questions:

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?

How to&Answers:

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:

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.