PHP Documentation Standards
Single line comment
// Double forward slash will comment everything after it.
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. */
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) */
/** * 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. */