CodeSniffer File Doc Comment And Class Doc Comment

14th October 2008 - 4 minutes read time

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.

PHP

Comments

Thank you so much :D

Submitted by den on Mon, 07/22/2019 - 17:58

Permalink

The excellent answer, I congratulate

Submitted by iHerb Code on Tue, 10/18/2022 - 19:13

Permalink

Thanks you!

Submitted by Mahmudjon on Thu, 06/29/2023 - 19:39

Permalink

Add new comment

The content of this field is kept private and will not be shown publicly.
CAPTCHA
8 + 2 =
Solve this simple math problem and enter the result. E.g. for 1+3, enter 4.
This question is for testing whether or not you are a human visitor and to prevent automated spam submissions.

Related Content

Recreating Spotify Wrapped In PHP

17th March 2024

I quite like the end of the year report from Spotify that they call "Wrapped". This is a little application in which they tell you what your favorite artist was and what sort of genres you listened to the most during the year.

Read more

Should A Constructor Throw An Exception?

18th February 2024

Let's say you had a class that you wanted to use, but there was some sort of error in creating the object. This might be that the wrong parameters were passed, or the third party service (eg. a database) wasn't available at the time of creation.

Read more

PHP Question: Variable Reference

10th December 2023

Question

What does the following code print out?

function arrayPrint($array)
{
   echo implode(' ', $array);
}

$arrayA = [1, 2, 3];
$arrayB = $arrayA;
$arrayB[1] = 0;
arrayPrint($arrayA);

Read more

Creating An Authentication System With PHP and MariaDB

15th October 2023

Using frameworks to handle the authentication of your PHP application is perfectly fine to do, and normally encouraged. They abstract away all of the complexity of managing users and sessions that need to work in order to allow your application to function.

Read more

Creating Sparklines In PHP

17th September 2023

A sparkline is a very small line graph that is intended to convey some simple information, usually in terms of a numeric value over time. They tend to lack axes or other labels and are added to information readouts in order to expand on numbers in order to give them more context.

Read more