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.

In some special cases – such as our implementation of hash notations – our standards are derived from the draft PSR-5 recommendations. This does not mean we are attempting to be “PSR-5 compliant” at this time, it simply means that we’ve adopted PSR-5 recommendations in part.

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
  • File headers
  • Constants

Documenting Tips #

Language: Summaries (formerly 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 permissible 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 DocBlocks can be parsed properly for inclusion in the code reference.

General #

DocBlocks should directly precede the hook, action, function, method, or class line. There should not be any opening/closing tags or other things between the DocBlock and the declarations to prevent the parser becoming confused.

Top ↑

Summary (formerly Short Description) #

No HTML markup or Markdown of any kind should be used in the summary. If the text refers to an HTML element or tag, then it should be written as “image tag”, not “<img>”. For example:

  • Good: Fires when printing the link tag in the header.
  • Bad: Fires when printing the <link> tag in the header.

Inline PHPDoc tags may be used.

Top ↑

Description (formerly Long Description) #

HTML markup should never be used outside of code examples, though Markdown can be used, as needed, in the description.

1. Lists:

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

 * Description which includes an unordered list:
 *
 * - This is item 1.
 * - This is item 2.
 * - This is item 3.
 *
 * The description continues on...

Use numbers to create an ordered list, with a blank line before and after.

 * Description which includes an ordered list:
 *
 * 1. This is item 1.
 * 2. This is item 2.
 * 3. This is item 3.
 *
 * The 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. Blank lines in code samples also need to be indented by four spaces.

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

3. Links in the form of URLs, such as related Trac tickets or other documentation, should be added in the appropriate place in the block using the @link tag.

Top ↑

Other Descriptions #

@param, @type, @return, or @since tags: No HTML should be used in the descriptions for these tags, though limited Markdown can be used as necessary, such as for adding backticks around variables, e.g. `$variable`.

  • Inline @see tags can also be used to auto-link to other elements in core:
    • Functions, e.g. {@see wp_list_pluck()}
    • Classes, e.g. {@see WP_Query}
    • Methods, e.g. {@see WP_Screen::add_help_tab()}
    • Hooks, e.g. {@see 'save_post'}
  • Default or available values should use single quotes, e.g. ‘draft’. Translatable strings should be identified as such in the description.
  • HTML elements and tags should be written as “audio element” or “link tag”.

Top ↑

DocBlock Formatting #

The examples provided in each section below show the expected block content and tags, as well as the exact formatting. Use spaces inside the block, not tabs, and ensure that items in each tag group are aligned according to the examples.

Top ↑

1. Functions and Class Methods #

Functions and class methods should be formatted as follows:

  • Summary: A brief, one sentence explanation of the purpose of the function spanning a maximum of two lines. Use a period at the end.
  • Description: A supplement to the summary, providing a more detailed description. Use a period at the end.
  • @ignore Used when an element is meant only for internal use and should be skipped from parsing.
  • @since x.x.x: Should always be 3-digit (e.g. @since 3.9.0). Exception is @since MU.
  • @access: Only use for standalone 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: Reference to a function, method, or class that is heavily-relied on. See the note above about inline @see tags for expected formatting.
  • @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. If multiple globals are listed, they should be aligned by type, variable, and description, with each other as a group.
  • @param: Note if the parameter is Optional before the description, and include a period at the end. For example: Optional. This value does something. Default empty.
  • @return: Should contain all possible return types, and a description for each. Use a period at the end. Note: @return void should not be used outside of the default bundled themes.
/**
 * 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.
 */

Top ↑

1.1 Parameters That Are Arrays #

Parameters that are an array of arguments should be documented in the “originating” function only, and cross-referenced via an @see tag in corresponding DocBlocks.

Array values should be documented using WordPress’ flavor of hash notation style similar to how Hooks can be 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)

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

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x 
 * @access (for functions: only use if private)
 *
 * @param type  $var Description.
 * @param array $args {
 *     Optional. An array of arguments.
 *
 *     @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.
 */

In most cases, there is no need to mark individual arguments in a hash notation as optional, as the entire array is usually optional. Specifying “Optional.” in the hash notation description should suffice.

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.

/**
 * Summary.
 *
 * Description.
 *
 * @since x.x.x
 * @deprecated x.x.x Use {@see 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:

  • Summary: Use a period at the end.
  • @since x.x.x: Should always be 3-digit (e.g. @since 3.9.0). Exception is @since MU.
  • @access: If the property is private, protected or public.
  • @var: Formatted the same way as @param, though the description may be omitted.
/**
 * Summary.
 *
 * @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 summary description DocBlock. Optionally, this may apply to inline get_template_part() calls as needed for clarity.

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

  • Summary: A brief, one line explanation of the purpose of the hook. Use a period at the end.
  • Description: A supplemental description to the summary, if warranted.
  • @ignore Used when a hook is meant only for internal use and should be skipped from parsing.
  • @since x.x.x: Should always be 3-digit (e.g. @since 3.9.0). Exception is @since MU.
  • @param: If the parameter is an array of arguments, document each argument using the PHPDoc hash notation, and 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.

/**
 * Summary.
 *
 * 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 DocBlock should be placed on the line immediately before the start of the HTML block or conditional, even if it means forcing line-breaks/PHP tags in a continuous line of HTML.

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 DocBlock 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. If multiple instances of the hook were added in the same release, document the one most logically placed as the “primary”.

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

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

Top ↑

6. File Headers #

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
 * @since x.x.x (if available)
 *
 * @package WordPress
 * @subpackage Component
 */

Top ↑

7. Constants #

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

Constants should be formatted as follows:

  • Summary: Use a period at the end.
  • @since x.x.x: Should always be 3-digit (e.g. @since 3.9.0). Exception is @since MU.
  • @var: Formatted the same way as @param.
/**
 * Summary.
 *
 * @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, tags are used correctly, but not all the time. For instance, sometimes you’ll see an @link tag inline, linking to a separate function or method. The proper tag to use is @see, and would be listed under the Related Functions 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 below 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. Should be accompanied by a matching @see tag.
@global type global
$varname
description
Document global(s) used in the function/method. For boolean and integer types, use bool and int, respectively.
@internal information string Typically used for adding notes for internal use only.
@ignore (standalone) Used to skip parsing of the entire element.
@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.
@package packagename Specifies package that all functions, includes, and defines in the file belong to. Found in DocBlock 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. For boolean and integer types, use bool and int, respectively.
@return datatype description Document the return value of functions or methods. @return void should not be used outside of the default bundled themes. For boolean and integer types, use bool and int, respectively.
@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 or Parameters That Are Arrays sections for example syntax.
@uses class::methodname()
class::$variablename
functionname()
Note: This tag has been used in the past, but should no longer be used.
References a key function/method used. May include a short description.
@var datatype description Data type for a class variable and short description. Callbacks are marked callback.

Note: PHPDoc tags work with some text editors/IDEs 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 DocBlocks:

Top ↑

Deprecated Tags #

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

Only when the new – external – PSR-5 recommendations are finalized, will across-the-board changes be considered, such as deprecating certain tags.

As proposed in the new PSR-5 recommendations, the following PHPDoc tag should be deprecated:

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

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_Fifteen.

@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 #