PHP Documentation Standards

Resources

WP PHP Coding Standards

DocBlocks

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

Comments

Single line comments

// Allow plugins to filter an array.

Multi-line comments

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