Существует ли стандарт PHPCS, предназначенный для докблоков PHP?

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.xml

Answer 2

В 2017 году у вас теперь больше возможностей:

• TypeHintDeclarationSniff от SlevomatCodingStandard лучше всего подходит для проверки докблоков, отлично работает с PHP 7, PHP 7.1, удаляет неиспользуемые документы и т. д.
• Также вы можете использовать другой инструмент - PHP-CS-Fixer, там вы найдете больше исправлений, которые помогут вам с docblock, просто выполните поиск "doc".

Answer 3

Отказ от ответственности: я автор ректора.

В 2019 году вы можете использовать статический анализ для завершения @var типы или объявления типов для вас.

class SomeClass
{
    private $value;

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

Зная это, Ректор автоматически заполняет тип var:

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

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

Подобный подход работает для типов возвращаемых данных, типов PHP 7.4 и объявлений типов из родительских интерфейсов и классов. Все поддерживается ректором.

Подробнее читайте в разделе Как заполнять объявления типов без доклблока с ректором