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

Question

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

选项1：

选项 2：

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

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

感谢您的时间。

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

score 4 · Accepted Answer

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

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

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

PHP 直到 7.x

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

自 PHP 8 起

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

PSR 标准

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

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

我会坚持使用Option 1。从代码完成的角度来看，这非常有益。

1 回答 1