Каков наилучший способ документировать, для phpdocumentor2, метод, который является генератором.
Я не думаю, что @return действительно работает для yield, но я не могу найти подходящую альтернативу.
Это только вопрос ожидания phpdoc, чтобы догнать?
Я пошел с @return Generator|SomeObject[], где SomeObject - это то, что у вас получилось.
PhpStorm также хорошо справляется с этим, так как теперь он обычно подсказывает методы Generator, а при повторе он указывает методы SomeObject.
(Тем не менее, я бы предпочел нативный @yield.)
Когда функция генератора вызывается в первый раз, объект возвращается внутренний класс Generator.
Таким образом, строго говоря, @return Generator был бы правильным, хотя и не описал бы, что вы можете ожидать, когда будете перебирать генератор.
Для практических целей получение значения означает возврат массива значений. Поэтому наиболее полезным было бы указать массив конкретных типов в качестве возвращаемого значения.
Как отмечено в комментариях, есть предостережения, но с завершением рабочего типа перевешивает их в моем сознании. Поэтому, с точки зрения удобства использования, я не вижу лучшего способа сделать это до тех пор, пока это не будет устранено в восходящем потоке.