用于记录 PHP 代码的官方 PHPDoc 参考

Question

我正在将我的项目升级到 PHP 8.0+。到目前为止，在代码注释中，我使用了@param和@return标签，如“选项 1”，而不是“选项 2”：

选项1：

• @param string[] ...。
• @return User[] ...。

选项2：

• @param array ...。
• @return array ...。

不过，因为我不知道第一种形式是否被官方允许，所以我开始问自己，切换到第二种形式是否会更好......所以，我想问你：有吗？有没有可用的 PHP 代码文档官方PHPDoc 参考资料？

另外，是否建议使用第一个选项而不是第二个选项？换句话说：是否有任何反对的论据——也考虑到未来？

感谢您的时间。

PS ：我找到了PHPDocumentor的参考资料，但我有一种感觉，它不是官方的 PHP 参考资料，而且还不兼容 PHP 8.0+。

Answer 1

PHPDoc 不是官方文档的一部分，但由于它已被如此广泛地采用，我非常怀疑它会被忽略。

PHP 版本 8 之前的版本仅定义了注释语法https://www.php.net/manual/en/language.basic-syntax.comments.php，其中不包含任何@相关元素。

PHP 版本 8 引入了属性 https://www.php.net/manual/en/language.attributes.overview.php，它将成为注释的本机替代品。

例如https://api-platform.com/docs/core/filters/

PHP 直到 7.x

/**
 * @ApiResource(attributes={"filters"={"offer.date_filter"}})
 */
class Offer
{
    // ...
}

从 PHP 8 开始

#[ApiResource(attributes: ['filters' => ['offer.date_filter']])]
class Offer
{
    // ...
}

PSR标准

PHPFig定义了2个PSR标准（尚未批准）

• PSR-5 https://github.com/php-fig/fig-standards/blob/master/propose/phpdoc.md
• PSR-19 https://github.com/php-fig/fig-standards/blob/master/propose/phpdoc-tags.md

不过，因为我不知道第一种形式是否被官方允许，所以我开始问自己，切换到第二种形式是否会更好......

我将坚持选择 1。从代码完成的角度来看，这非常有益。