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?
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
.)
SomeObject
(or \SomeObject
) in @return
to prompt SomeObject's methods. PhpStorm needs extra []
at the end of type (SomeObject[]
). So I thinkbest option is to write it like @Robbert wrote: @return Generator|\SomeObject[]
.
Jun 2, 2016 at 11:04
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.
@return
is appropriate, since it denotes what you get back from the generator.@return
is certainly incorrect. Most likely the syntax will be either@yield V
or@return Generator<V>
, maybe with the ability to specify K, S and R as well. See also github.com/phpDocumentor/fig-standards/issues/5