是否有针对 PHP 文档块的 PHPCS 标准？答案

【问题标题】：Is there a PHPCS standard targeting PHP docblocks?是否有针对 PHP 文档块的 PHPCS 标准？
【发布时间】：2020-05-19 04:12:16
【问题描述】：

是否有 PHPCS 编码标准可以检查文档块中是否存在正确的注释（@param、@return、@throws 等），包括它们之间的适当间距？

【问题讨论】：

标签： php phpdoc codesniffer

【解决方案1】：

尝试运行以下命令，看看它是否会产生您想要的结果：

phpcs /path/to/code --standard=Squiz --sniffs=Squiz.Commenting.FunctionComment,Squiz.Commenting.FunctionCommentThrowTag,Squiz.Commenting.ClassComment,Squiz.Commenting.FileComment,Squiz.Commenting.VariableComment

如果是这样，您可以创建自己的标准，只包括那些嗅探，以及您想要检查的任何其他内容。为此，您可以创建一个 ruleset.xml 文件并将其用作您的标准。

例如，您可以创建一个名为 mystandard.xml 的文件并包含以下内容：

<?xml version="1.0"?>
<ruleset name="MyStandard">
  <description>My custom coding standard.</description>
  <rule ref="Squiz.Commenting.FunctionComment" />
  <rule ref="Squiz.Commenting.FunctionCommentThrowTag" />
  <rule ref="Squiz.Commenting.ClassComment" />
  <rule ref="Squiz.Commenting.FileComment" />
  <rule ref="Squiz.Commenting.VariableComment" />
</ruleset>

然后你可以运行这个命令：

phpcs /path/to/code --standard=/path/to/mystandard.xml

您还可以在 ruleset.xml 文件中执行其他操作。在此处查看文档：https://github.com/squizlabs/PHP_CodeSniffer/wiki/Annotated-Ruleset

【讨论】：

这个答案来自2012年。它仍然是正确的。但我今天要补充一点，您也可以使用 Generic.Commenting.DocComment 嗅探。这些嗅探器的行为略有不同，因此请选择最适合您风格的嗅探器。
推荐把-s扔到phpcs参数列表中；它将准确显示您的代码触发了哪个嗅探，这对于调试和构建规则列表很有用。

【解决方案2】：

2017 年您现在有更多选择：

检查文档块的最佳嗅探器之一是 TypeHintDeclarationSniff from SlevomatCodingStandard，它适用于 PHP 7、PHP 7.1，删除未使用的文档等。
你也可以使用另一个工具 - PHP-CS-Fixer，在那里你可以找到更多的修复程序，这将帮助你处理 docblock，只需搜索“doc”

【讨论】：

【解决方案3】：

免责声明：我是 Rector 的作者。

2019年您可以使用静态分析为您完成@var类型或类型声明。

class SomeClass
{
    private $value;

    public setValue(string $string)
    {
        // here we know the string type is assigned
        $this->value = $value;
    }    
}

知道了，Rector 自动完成 var 类型：

class SomeClass
{
    /**
     * @var string
     */
    private $value;

    public setValue(string $string)
    {
        $this->value = $value;
    }    
}

类似的方法适用于返回类型、PHP 7.4 类型以及来自父接口和类的类型声明。全部由 Rector 支持。

【讨论】：