WordPress uses a customized documentation schema that draws inspiration from PHPDoc, an evolving standard for providing documentation to PHP code, which is maintained by phpDocumentor. Where there may be ambiguity, the proposed phpDoc recommendation can be consulted as a secondary reference.

What Should Be Documented #

PHP documentation in WordPress mostly takes the form of either formatted blocks of documentation or inline comments.

The following is a list of what should be documented in WordPress files:

  • Functions and class methods
  • Classes
  • Class properties
  • Requires and includes
  • Hooks (actions and filters)
  • Inline comments (where necessary)
  • File headers
  • Constants

Documenting Tips #

Language: Short descriptions should be clear, simple, and brief. Document “what” and “when” – “why” should rarely need to be included. For example:

  • Functions: What does the function do?
    • Good: Display last modified date for a post.
    • Bad: Displays the date on which the post was last modified.
  • Filters: What is being filtered?
    • Good: Filter the post content.
    • Bad: Lets you edit the post content that is output in the post template.
  • Actions: When does an action fire?
    • Good: Fires after most of core is loaded, and the user is authenticated.
    • Bad: Allows you to register custom post types, custom taxonomies, and other general housekeeping tasks after a lot of WordPress core has loaded.

@since: The recommended tool to use when searching for the version something was added to WordPress is svn blame. An additional resource for hooks is the WordPress Hooks Database.

If, after using these tools, the version number cannot be determined, use @since Unknown.

Anything ported over from WPMU should use @since MU. Existing @since MU tags should not be changed.

Code Refactoring: It is permissable to space out the specific action or filter lines being documented to meet the coding standards, but do not refactor other code in the file.

Top ↑

Formatting Guidelines #

The following guidelines should be followed to ensure that the content of the doc blocks can be parsed properly for inclusion in the code reference.

Short descriptions:

No markup of any kind. If the description refers to an HTML element or tag, then it should be written as “link tag”, not “<link>”. For example: Fires when printing the link tag in the header.

Long descriptions:

Markdown can be used, if needed, in a long description.

1. Use a hyphen (-) to create an unordered list, with a blank line before and after.

 * Long description which includes a list:
 *
 * - This is item 1.
 * - This is item 2.
 * - This is item 3.
 *
 * The long description continues on...

2. Code samples would be created by indenting every line of the code by 4 spaces, with a blank line before and after.

 * Long description which includes a code sample:
 *
 *    $status = array(
 *        'draft'          => __('Draft'),
 *        'pending'        => __('Pending Review'),
 *        'private'        => __('Private'),
 *        'publish'        => __('Published')
 *        );
 *
 * The long description continues on...

3. No inline links or other tags. Links, such as related Trac tickets or other documentation, should be added in the appropriate place in the block using the @link tag.

Other descriptions:

@param, @type, or @return tags: No HTML or markdown is permitted in the descriptions for these tags. HTML elements and tags should be written as “audio element” or “link tag”. @return void should not be used outside of the default bundled themes.

Top ↑

PHPDoc Block Formatting #

Top ↑

1. Functions and Class Methods #

Functions and class methods should be formatted as follows:

  • Short description: A brief, one line explanation of the purpose of the function. Use a period at the end.
  • Long description: A supplement to the short description, providing a more detailed description. Use a period at the end.
  • @since x.x.x: Should always be 3-digit (e.g. @since 3.6.0). Exception is @since MU.
  • @access: Only use for functions if private. If the function or class method is private, it is intended for internal use only, and there will be no documentation for it in the code reference.
  • @see: The function, method, or class relied on.
  • @link: URL that provides more information.
  • @global: List PHP globals that are used within the function or method, with an optional description of the global.
  • @param: Note if the parameter is Optional before the description, and include a period at the end.
  • @return: Note the period after the description.
/**
 * Short description. (use period)
 *
 * Long description.
 *
 * @since x.x.x
 * @access (for functions: only use if private)
 *
 * @see Function/method/class relied on
 * @link URL
 * @global type $varname Short description.
 *
 * @param  type $var Description.
 * @param  type $var Optional. Description.
 * @return type Description.
 */

1.1 Parameters That Are Arrays #

Parameters that are argument arrays should be documented in the “originating” function only, and back-referenced via an @see tag in corresponding PHPDoc blocks.

Array values should be documented using the PHPDoc hash notation style similar to how Hooks are documented, each array value beginning with the @type tag, and taking the form of:

* @type type $key Description. Default <value>. Accepts <value>, <value>.
*                 (aligned with Description, if wraps to a new line)

To avoid unnecessary duplication, argument arrays should only be documented in the “originating” function or method, and back-referenced via an @see tag in corresponding PHPDoc blocks.

An example of an “originating” function and argument array re-use might be wp_remote_request|post|get|head().

/**
 * Short description. (use period)
 *
 * Long description.
 *
 * @since x.x.x 
 * @access (for functions: only use if private)
 *
 * @param type $var Description.
 * @param array $args {
 *     An array of arguments. Optional.
 *
 *     @type type $key Description. Default <value>. Accepts <value>, <value>.
 *                     (aligned with Description, if wraps to a new line)
 *     @type type $key Description.
 * }
 * @param type $var Description.
 * @return type Description.
 */

Top ↑

1.2 Deprecated Functions #

If the function is deprecated and should not be used any longer, the @deprecated tag, along with the version and description of what to use instead, should be added.

/**
 * Short description. (use period)
 *
 * Long description.
 *
 * @since x.x.x
 * @deprecated x.x.x Use new_function_name() instead.
 * @see new_function_name()
 *
 * @param type $var Optional. Description.
 * @param type $var Description.
 * @return type Description.
 */

Top ↑

2. Class Properties #

Class properties should be formatted as follows:

  • Short description: Use a period at the end.
  • @since x.x.x: Should always be 3-digit (e.g. @since 3.6.0). Exception is @since MU.
  • @access: If the property is private, protected or public. Private properties are intended for internal use only.
  • @var: Formatted the same way as @param.
/**
 * Short description. (use period)
 *
 * @since x.x.x
 * @access (private, protected, or public)
 * @var type $var Description.
 */

Top ↑

3. Requires and Includes #

Files required or included should be documented with a short description PHPDoc block. Optionally, this may apply to inline get_template_part() calls as needed for clarity.

/**
 * Short description. (use period)
 */
require_once( ABSPATH . '/filename.php' );

Top ↑

4. Hooks (Actions and Filters) #

Both action and filter hooks should be documented on the line immediately preceding the call to do_action() or apply_filters(), and formatted as follows:

  • Short description: A brief, one line explanation of the purpose of the hook. Use a period at the end.
  • Long description: A supplemental description to the short description, if warranted.
  • @since x.x.x: Should always be 3-digit (e.g. @since 3.6.0). Exception is @since MU.
  • @param: If the parameter is an array of arguments, document each argument using the PHPDoc hash notation, include a period at the end of each line.

Note that @return is not used for hook documentation, because action hooks return nothing, and filter hooks always return their first parameter.

/**
 * Short description. (use period)
 *
 * Long description.
 *
 * @since x.x.x
 *
 * @param type $var Description.
 * @param array $args {
 *     Short description about this hash.
 *
 *     @type type $var Description.
 *     @type type $var Description.
 * }
 * @param type $var Description.
 */

If a hook is in the middle of a block of HTML or a long conditional, the PHPDoc block should be placed on the line immediately before the start of the HTML block or conditional.

Tools to use when searching for the version a hook was added are svn blame, or the WordPress Hooks Database. If, after using these tools, the version number cannot be determined, use @since Unknown.

Top ↑

4.1 Duplicate Hooks #

Occasionally, hooks will be used multiple times in the same or separate core files. In these cases, rather than list the entire PHPDoc block every time, only the first-added version of an action or filter will be fully documented. Subsequent versions should have a single-line comment.

For actions:

/** This action is documented in path/to/filename.php */ 

For filters:

/** This filter is documented in path/to/filename.php */

To determine which instance should be documented, search for multiples of the same hook tag, then use svn blame to find the first use of the hook in terms of the earliest revision.

Top ↑

5. Inline Comments #

Inline comments inside methods and functions should be formatted as follows:

Top ↑

5.1 Single line comments #

// Allow plugins to filter an array.

Top ↑

5.2 Multi-line comments #

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

Top ↑

6. File Headers #

The PHPDoc file header block 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.

/**
 * Short Description (no period for file headers)
 *
 * Long Description.
 *
 * @link URL
 * @since x.x.x (if available)
 *
 * @package WordPress
 * @subpackage Component
 */

Top ↑

7. Constants #

The PHPDoc constant block is used to give a description of the constant for better use and understanding.

Constants should be formatted as follows:

  • Short description: Use a period at the end.
  • @since x.x.x: Should always be 3-digit (e.g. @since 3.6.0). Exception is @since MU.
  • @var: Formatted the same way as @param.
/**
 * Short Description. (use period)
 *
 * @since x.x.x (if available)
 * @var type $var Description.
 */

Top ↑

PHPDoc Tags #

Common PHPDoc tags used in WordPress include @since, @see, @link, @param, and @return (see table below for full list).

For the most part, they are used correctly, but not all the time. For instance, sometimes you’ll see a @link tag inline, linking to a separate function or method. The proper tag to use is @see, and would be listed under the Related Function section in the code reference.

Tag Usage Description
@access public
private
protected
Indicates access control for a function/method.
@access private indicates the function should not be documented.
Used directly above the @since line in block.
@deprecated version x.x.x replacement function name What version of WordPress the function/method was deprecated. Use 3-digit version number.
@global type global $varname Notes a global used in the function/method.
@internal information string Typically used for adding notes for internal use only.
@link URL Link to additional information for the function/method.
For an external script/library, links to source.
Not to be used for related functions/methods; use @see instead.
@method returntype description Shows a “magic” method found inside the class.
@name $globalvarname Used to rename a global variable for documentation to make it more readable.
@package packagename Specifies package that all functions, includes, and defines in the file belong to. Found in doc block at top of the file. For core (and bundled themes), this is always WordPress.
@param datatype $variable description Function/method parameter of the format: parameter type, variable name, description, default behavior.
@return datatype description Document the return value of functions or methods. @return void should not be used outside of the default bundled themes.
@see elementname References another function/method/class the function/method relies on.
@since version x.x.x Documents release version function/method was added. Use 3-digit version number this is to aid with version searches, and for use when comparing versions in code. Exception is @since MU
@subpackage subpackagename For page-level docblock, specifies the Component that all functions and defines in file belong to. For class-level docblock, specifies the subpackage/component the class belongs to.
@todo information string Documents planned changes to an element that have not been implemented.
@type datatype description for an argument array value Used to denote argument array value types. See the Hooks section for example syntax.
@uses class::methodname()
class::$variablename
functionname()
References a key function/method used. May include a short description.
Note: This tag has been used in the past, but should no longer be used.
@var datatype description Data type for a class variable and short description. Callbacks are marked callback.

Tip: PHPDoc tags work with some text editors to display more information about a piece of code. It is useful to developers using those editors to understand what the purpose is, and where they would use it in their code.

The following text editors/IDEs have extensions/bundles you can install that will help you auto-create a PHPDoc comment block:

Top ↑

Deprecated Tags #

Preface: For the time being, and for the sake of consistency, WordPress Core will continue to use @subpackage and @var tags both when writing new PHPDoc blocks, and editing old ones.

Only when the new external PHPDoc standards are finalized, will across-the-board changes be considered, such as deprecating certain tags.

As proposed in the new phpDocumenter standard, the following PHPDoc tags should be deprecated:

  • @subpackage (in favor of a unified package tag: @package Package\Subpackage)
  • @var (in favor of @type)

Top ↑

Other Tags #

@package Tag in Plugins and Themes (bundled themes excluded)

Third-party plugin and theme authors must not use @package WordPress in their plugins or themes. The @package name for plugins should be the plugin name; for themes, it should be the theme name, spaced with underscores: Twenty_Thirteen.

@author Tag

It is WordPress’ policy not to use the @author tag, except in the case of maintaining it in external libraries. We do not want to imply any sort of “ownership” over code that might discourage contribution.

@copyright and @license Tags

The @copyright and @license tags are used in external libraries and scripts, and should not be used in WordPress core files.

  • @copyright is used to specify external script copyrights.
  • @license is used to specify external script licenses.

Top ↑

Resources #