PHP Documentation Standards

DocBloc Examples

Single line comment

// Double forward slash will comment everything after it.

Multi-line comment

Multi-line comments must not begin with /** (double asterisk) as the parser might mistake it for a DocBlock. Use /* (single asterisk) instead.

/* 
 * 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.
 */

File Header

The file header DocBlock is used to give an overview of what is contained in the file. Whenever possible, all WordPress files should contain a header block, regardless of the file’s contents – this includes files containing classes.

/**
 * Summary (no period for file headers)
 *
 * Description. (use period)
 *
 * @link URL
 *
 * @package WordPress
 * @subpackage Component
 * @since x.x.x (when the file was introduced)
 */

Class

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 */

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.
 */

More Resources