昨天我写了两篇有关CodeSniffer的文章，并警告我找不到任何合适的文档。我以为今天我会检查一些我也很难找到的东西，这是文件doc错误。当您在类上运行CodeSniffer时，您可能会发现正在产生以下错误。
$ phpcs MyClass.php FILE: MyClass.php -------------------------------------------------------------------------------- FOUND 1 ERROR(S) AND 0 WARNING(S) AFFECTING 1 LINE(S) -------------------------------------------------------------------------------- 2 | ERROR | Missing file doc comment --------------------------------------------------------------------------------
大多数开发人员应该熟悉文档注释。它们用作注释的标准模型，也可以用于自动生成API文档。CodeSniffer文档没有解释的是文件doc注释和类doc注释之间的区别。类文档注释是在类之前的注释，它不仅描述类的作用，而且还提供作者，版本和许可证信息。这是一个典型（且非常简单）的类文档注释。@符号用于生成API文档。
<?php
/**
* MyClass Class Doc Comment
*
* @category Class
* @package MyPackage
* @author A N Other
* @license http://www.gnu.org/copyleft/gpl.html GNU General Public License
* @link http://www.nhooo.com/
*
*/
class MyClass{
}文件doc注释位于文件的顶部，在任何include语句的上方，并且包含与类doc注释几乎相同的信息。当添加到您的应用程序中时，您的文档结构可能如下所示。
<?php
/**
* MyClass File Doc Comment
*
* @category MyClass
* @package MyPackage
* @author A N Other
* @license http://www.gnu.org/copyleft/gpl.html GNU General Public License
* @link http://www.nhooo.com/
*
*/
include('anotherclass.php');
/**
* MyClass Class Doc Comment
*
* @category Class
* @package MyClass
* @author A N Other
* @license http://www.gnu.org/copyleft/gpl.html GNU General Public License
* @link http://www.nhooo.com/
*
*/
class MyClass{
}只要确保不同行的间距正确，并且类注释和第一个参数之间只有一个空行，您就应该发现运行CodeSniffer不会产生任何错误。您还将能够生成一些非常整洁的文档，可以将其与应用程序捆绑在一起。