Menu

Documentation Standards in PHP

In this post we take a look at the phpDocumentor standards, and not the conventional documentation. phpDocumentor 2 is a tool that makes it possible to generate documentation directly from your PHP source code. With this you can provide your consumers with more information regarding the functionality embedded within your source and not just what is usable to them from your user interface.

Documentation generated by phpDocumentor 2 does not aim to be a replacement for conventional documentation but is rather supplemental, or reference, documentation

 

Why should we document our code?

First of all it’s much easier to understand another developer’s code and the way how it works. That means if you have guideline for a class or a complex function, it’s easier to understand and use them. Commenting your code helps you to keep it clean and readable.

 

What shuold be in a documentation block?

  • Summary
  • Description
  • Tags

 

What should be documented?

  1. Functions and class methods
  2. Class properties
  3. Requires and includes
  4. Inline comments
  5. File headers
  6. Constants

 

1. Functions and Class Methods:

Here you can find a list of the @tags you should use for functions and class methods.

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 * @access (for functions: only use if private)
 *
 * @see Function/method/class relied on
 * @link URL
 * @global type $varname Description.
 * @global type $varname Description.
 *
 * @param type $var Description.
 * @param type $var Optional. Description.
 * @return type Description.
 */

 

2. Class Properties

Here you can find a list of the @tags you should use for class properties.

/**
 * Summary.
 *
 * @since x.x.x
 * @access (private, protected, or public)
 * @var type $var Description.
 */

 

3. Requires and includes

/**
 * Summary.
 */
require_once( 'filename.php' );

 

4. Inline comments

Single line comment:

// Allow plugins to filter an array.

 Multi line comment:

/* 
 * This is a comment that is long enough to warrant being stretched over
 * the span of multiple lines. You'll notice this follows basically
 * the same format as the PHPDoc wrapping and comment block style.
 */

Note: multi line comment starts with /* and not /**

 

5. File Headers

The file header DocBlock is used to give an overview of what is contained in the file.

/**
 * Summary (no period for file headers)
 *
 * Description. (use period)
 *
 * @link URL
 * @since x.x.x (if available)
 *
 * @package Package
 * @subpackage SubPackage
 */

 

6. Constants

The constant DocBlock is used to give a description of the constant for better use and understanding.
Here you can find a list of the @tags you should use for constants.

/**
 * Summary.
 *
 * @since x.x.x (if available)
 * @var type $var Description.
 */

 

Resources:
– phpDocumentor original documentation: http://www.phpdoc.org/docs/latest/index.html
– WordPress PHP documentation standards: https://make.wordpress.org/core/handbook/inline-documentation-standards/php-documentation-standards/

Have something on your mind?