php - 是否有针对 PHP 文档块的 PHPCS 标准？

Question

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

Answer 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

Answer 2

在 2017 年，您现在有更多选择：

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

Answer 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 在没有 Docblocks 的情况下完成类型声明