CodeSniffer File Doc Comment And Class Doc Comment

14th October 2008 - 3 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.

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

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.

  1. <?php
  2. /**
  3.  * MyClass Class Doc Comment
  4.  *
  5.  * @category Class
  6.  * @package MyPackage
  7.  * @author A N Other
  8.  * @license http://www.gnu.org/copyleft/gpl.html GNU General Public License
  9.  * @link http://www.hashbangcode.com/
  10.  *
  11.  */
  12. class MyClass{
  13. }

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.

  1. <?php
  2. /**
  3.  * MyClass File Doc Comment
  4.  *
  5.  * @category MyClass
  6.  * @package MyPackage
  7.  * @author A N Other
  8.  * @license http://www.gnu.org/copyleft/gpl.html GNU General Public License
  9.  * @link http://www.hashbangcode.com/
  10.  *
  11.  */
  12. include('anotherclass.php');
  13. /**
  14.  * MyClass Class Doc Comment
  15.  *
  16.  * @category Class
  17.  * @package MyClass
  18.  * @author A N Other
  19.  * @license http://www.gnu.org/copyleft/gpl.html GNU General Public License
  20.  * @link http://www.hashbangcode.com/
  21.  *
  22.  */
  23. class MyClass{
  24. }

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.

Comments

Permalink

Thank you so much :D

den (Mon, 07/22/2019 - 17:58)

Add new comment

The content of this field is kept private and will not be shown publicly.