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

Posted 2023-02-22

【中文标题】记录（phpdoc）生成器的最佳方法（产生的方法）

【英文标题】：Best way to document (phpdoc) generators (methods that yield)

【发布时间】：2015-07-16 23:17:26

【问题描述】：

对于 phpdocumentor2 来说，记录生成器的方法的最佳方法是什么。

我不认为 @return 真的适用于 yield，但我似乎找不到任何合适的替代方案。

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

【问题讨论】：

恕我直言@return 是合适的，因为它表示您从生成器返回的内容。

目前还没有指定的方法来做到这一点。你是对的，@return 肯定是不正确的。最有可能的语法是@yield V 或@return Generator<V>，也许还可以指定K、S 和R。另见github.com/phpDocumentor/fig-standards/issues/5

@NikiC 您的回复确实应该作为答案发布。

【参考方案1】：

From the PHP Manual:

第一次调用生成器函数时， 返回内部生成器类。

所以严格来说，@return Generator 是正确的，虽然不是超级描述您在迭代生成器时可以期望返回的内容。

【参考方案2】：

我选择了@return Generator|SomeObject[]，其中SomeObject 是产生的东西。

PhpStorm 也能很好地处理这个问题，因为它现在通常提示 Generator 方法，而在迭代时它会提示 SomeObject 方法。

（不过，我更喜欢原生的@yield。）

【讨论】：

编辑提示：Netbeans 只需要@return 中的SomeObject（或\SomeObject）来提示SomeObject 的方法。 PhpStorm 在类型末尾需要额外的 [] (SomeObject[])。所以我认为最好的选择是像@Robbert 写的那样写：@return Generator|\SomeObject[]。

从 PHP 7 开始，Generator->getReturn() 怎么样？

这将更难暗示。你有什么建议？

这是一个非常聪明的解决方案！

这应该是标记的答案。真的很有帮助。谢谢。