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
- PSR – PHP Standard Recommendation
- phpDocumentor enables you to generate documentation from your PHP source code.
- PEAR Docblock Comment standards
- The PHP Framework Interop Group
- WordPress PHP Documentation Standards