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

Question

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

选项 1：

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

选项 2：

@param array ....
@return array ....

虽然，因为我不知道第一种形式是否官方允许，我开始问自己，如果切换到第二种选择不是更好...所以，我想问你：有没有官方PHP文档参考文档PHP代码可用？

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

感谢您的宝贵时间。

P.S：我找到了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 标准

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

Though, because I don't know if the first form is officially allowed, I begin to ask myself, if it wouldn't be better to switch to the second option...

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

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

Official PHPDoc reference for documenting PHP code

php

documentation

phpdoc

code-documentation

phpdocumentor2