46

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?

pmaruszczyk
  • 2,157
  • 2
  • 24
  • 49
Mat-Locomotive
  • 811
  • 1
  • 8
  • 6
  • 1
    IMHO `@return` is appropriate, since it denotes what you get back from the generator. – Anticom May 06 '15 at 19:23
  • 8
    As of now there is no spec'd way to do this. You are correct in that `@return` is certainly incorrect. Most likely the syntax will be either `@yield V` or `@return Generator`, maybe with the ability to specify K, S and R as well. See also https://github.com/phpDocumentor/fig-standards/issues/5 – NikiC May 10 '15 at 09:11
  • @NikiC Your reply should really be posted as an answer. – meridius Jun 15 '16 at 10:42

3 Answers3

42

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.)

Update (2023): nowadays there's good support for the new format Generator<SomeObject> as well, as suggested by Thanh in a below answer. Duplicating it here for visibility.

Robbert
  • 5,063
  • 6
  • 36
  • 44
  • 1
    Editor hints: Netbeans just need a `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[]`. – pmaruszczyk Jun 02 '16 at 11:04
  • 1
    What about `Generator->getReturn()`, as of PHP 7? – SOFe Jul 28 '17 at 15:41
  • That's going to be even harder to hint. What do you suggest? – Robbert Jul 29 '17 at 18:33
  • That's a very clever solution! – AsTeR May 17 '18 at 15:44
  • This should be the marked answer. Really helpful. Thank you. – Lachezar Todorov Mar 01 '19 at 17:36
  • It is unfortunate, but adopting this has really bad consequences: from a static analysis point of view, the `|` means "or", this leads to the fact that a method declared with `@return Generator|SomeObject[]` means that it **either** return a Generator of untyped data, **or** strictly an `array` of `SomeObject`. – Patrick Allaert Jul 28 '20 at 11:36
  • @pmaruszczyk that is especially wrong.. `SomeObject` means one specific object, whereas `SomeObject[]` is an list of (possibly many) objects. The behaviour in Netbeans you described sounds like a bug. – Christian Apr 30 '23 at 11:02
12

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.

Maxime Rainville
  • 2,019
  • 23
  • 29
5

It's also possible to type the Generator

@return Generator<array|int>
Thanh Trung
  • 3,566
  • 3
  • 31
  • 42