记录（phpdoc）生成器（产生的方法）的最佳方式

Question

对于 phpdocumentor2，记录文档的最佳方法是什么，即生成器方法。

我不认为

@return

真的适用于

yield

，但我似乎找不到任何合适的替代方案。

这只是等待 phpdoc 赶上的问题吗？

Answer 1

我选择了

@return Generator|SomeObject[]

，其中

SomeObject

是正在产生的东西。

PhpStorm 也能很好地处理这个问题，因为它现在通常会提示

Generator

方法，并且在迭代时它会提示

SomeObject

方法。

（不过，我更喜欢本地人

@yield

。）

更新（2023）： 如今，新格式也得到了很好的支持

Generator<SomeObject>

，正如 Thanh 在下面的答案中所建议的那样。将其复制到此处以提高可见性。

Answer 2

当第一次调用生成器函数时，会生成一个对象返回内部 Generator 类。

所以严格来说，

@return Generator

是正确的，尽管它不能很好地描述迭代生成器时您可以期望得到的结果。

Answer 3

也可以输入生成器

@return Generator<array|int>

Answer 4

只想分享这个：

Generator 可以返回（调用 getReturn()）并支持 send() 方法。在yield的时候，我们可以认为生成的value有key和value。

考虑到以上所有因素，我们可以假设正确的注释应该包含四个元素：键、值、发送类型、返回类型。

例如：

@return Generator<int, string, string, void>

代表：当yield有int索引字符串时，send()返回字符串，当generator返回void时，结果就是结果。