CodeSniffer File Doc Comment And Class Doc Comment

Yesterday I wrote two posts about CodeSniffer and a common warning that I couldn't find any decent documentation on. I thought that today I would go over something that I also had trouble finding out about, this is the file doc error. When you run CodeSniffer on a class you might find the following error being produced.

$ phpcs MyClass.php
 
FILE: MyClass.php
--------------------------------------------------------------------------------
FOUND 1 ERROR(S) AND 0 WARNING(S) AFFECTING 1 LINE(S)
--------------------------------------------------------------------------------
 2 | ERROR | Missing file doc comment
--------------------------------------------------------------------------------

Most developers should be familiar with doc comments. They are used as a standard model for commenting and can also be used to generate API documentation automatically. What the CodeSniffer documentation doesn't explain is the difference between a file doc comment and a class doc comment. A class doc comment is a comment that precedes a class, it describes not only what the class does, but also gives author, version and license information. Here is a typical (and very simple) class doc comment. The @ symbols are used to generate the API documentation.

<?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.hashbangcode.com/
 *
 */
class MyClass{
}

A file doc comment is placed at the top of the file, above any include statements and contains pretty much the same information as the class doc comment. When added to your application your document structure might look like this.

<?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.hashbangcode.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.hashbangcode.com/
 *
 */
class MyClass{
}

As long as you make sure that different lines are spaced correctly, and that there is a single blank line between the class comment and the first parameter, you should find that running CodeSniffer will produce no errors. You will also be able to generate some pretty neat documentation which you can bundle with your application.