What Should Be Documented What Should Be Documented
- Functions and class methods
- Object properties
- File headers
Documenting Tips Documenting Tips
Short descriptions should be clear, simple, and brief. Document “what” and “when” – “why” should rarely need to be included. For example:
Functions and closures are third-person singular elements, meaning third-person singular verbs should be used to describe what each does.
Tip: Need help remembering how to conjugate for third-person singular verbs? Imagine prefixing the function, hook, class, or method summary with “It”:
- Good: “(It) Does something.”
- Bad: “(It) Do something.”
Functions: What does the function do?
- Good: Handles a click on X element.
- Bad: Included for back-compat for X element.
since: The recommended tool to use when searching for the version something was added to WordPress is svn blame.
If, after using these tools, the version number cannot be determined, use
Code Refactoring: Do not refactor code in the file when changes to the documentation.
Descriptive elements should be written as complete sentences. The one exception to this standard is file header summaries, which are intended as file “titles” more than sentences.
The serial (Oxford) comma should be used when listing elements in summaries, descriptions, and parameter or return descriptions.
Formatting Guidelines 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 should be a single sentence and contain no markup of any kind. If the description refers to an HTML element or tag, then it should be written as “link tag”, not “”. For example: “Fires when printing the link tag in the header”.
Markdown can be used, if needed, in a long description. Lines should be
param and 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”.
Line wrapping Line wrapping
DocBlock text should wrap to the next line after 80 characters of text. If the DocBlock itself is indented on the left 20 character positions, the wrap could occur at position 100, but should not extend beyond a total of 120 characters wide.
Functions should be formatted as follows:
- Long description: A supplement to the short description, providing a more detailed description. Use a period at the end.
- @summary: Short description – a brief, one line explanation of the purpose of the function. Use a period at the end.
- deprecated x.x.x: Only use for deprecated functions, and provide the version the function was deprecated which should always be 3-digit (e.g. since 3.6.0), and the function to use instead.
- since x.x.x: Should always be 3-digit (e.g. since 3.6.0).
- access: Only use for functions if private. If the function is private, it is intended for internal use only, and there will be no documentation for it in the code reference.
- @class: Use for class constructors.
- @augments: For class constuctors, list class inheritance chain from direct parent to eldest ancestor.
- @mixes: List mixins that are mixed into the object.
- static: For classes, used to mark that a function is a static method on the class constructor.
- see: A function or class relied on.
- link: URL that provides more information.
- @fires: Event fired by the function.
- @listens: Events this function listens for.
- param: Give a brief description of the variable; denote particulars (e.g. if the variable is optional, its default) with JSDoc @param syntax.
- return: Note the period after the description.
/** * @summary Short description. (use period) * * Long. (use period) * * @since x.x.x * @deprecated x.x.x Use new_function_name() instead. * @access private * * @class * @augments superclass * @mixes mixin * * @see Function/class relied on * @link URL * @global type $varname Short description. * @fires target:event * @listens target:event * * @param type $var Description. * @param type $var Optional. Description. * @return type Description. */
Object Properties Object Properties
Object 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).
access: If the property is private, protected or public. Private properties are intended for internal use only.
property: Formatted the same way as param.
/** * Short description. (use period) * * @since x.x.x * @access (private, protected, or public) * @property type $var Description. */
Inline Comments Inline Comments
Inline comments inside methods and functions should be formatted as follows:
Single line comments Single line comments
// Extract the array values.
Multi-line comments 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 JSDoc wrapping and comment block style. */
File Headers File Headers
The JSDoc file header block is used to give an overview of what is contained in the file.
Files or libraries required should be documented with a short description JSDoc block using the @requires tag.
WordPress uses JSHint for general code quality testing. Any inline configuration options should be placed at the end of the header block.
Supported JSDoc Tags Supported JSDoc Tags
|@abstract||This method can be implemented (or overridden) by the inheritor.|
|access||Specify the access level of this member (private, public, or protected).|
|@alias||Treat a member as if it had a different name.|
|@augments||This class inherits from a parent class.|
|author||Identify the author of an item.|
|@borrows||This object uses something from another object.|
|@callback||Document a callback function.|
|@class||This function is a class constructor.|
|@classdesc||Use the following text to describe the entire class.|
|@constant||Document an object as a constant.|
|@constructs||This function member will be the constructor for the previous class.|
|copyright||Document some copyright information.|
|@default||Document the default value.|
|deprecated||Document that this is no longer the preferred way.|
|@description||Describe a symbol.|
|@enum||Document a collection of related properties.|
|@event||Document an event.|
|example||Provide an example of how to use a documented item.|
|@external||Document an external class/namespace/module.|
|@file||Describe a file.|
|@fires||Describe the events this method may fire.|
|@function||Describe a function or method.|
|global||Document a global object.|
|ignore||[todo] Remove this from the final output.|
|@inner||Document an inner object.|
|@instance||Document an instance member.|
|@kind||What kind of symbol is this?|
|@lends||Document properties on an object literal as if they belonged to a symbol with a given name.|
|license||[todo] Document the software license that applies to this code.|
|link||Inline tag – create a link.|
|@member||Document a member.|
|memberof||This symbol belongs to a parent symbol.|
|@mixes||This object mixes in all the members from another object.|
|@mixin||Document a mixin object.|
|name||Document the name of an object.|
|namespace||Document a namespace object.|
|param||Document the parameter to a function.|
|@private||This symbol is meant to be private.|
|property||Document a property of an object.|
|@protected||This member is meant to be protected.|
|@public||This symbol is meant to be public.|
|@readonly||This symbol is meant to be read-only.|
|@returns||Document the return value of a function.|
|see||Refer to some other documentation for more information.|
|since||When was this feature added?|
|static||Document a static member.|
|@summary||A shorter version of the full description.|
|@this||What does the ‘this’ keyword refer to here?|
|@throws||Describe what errors could be thrown.|
|todo||Document tasks to be completed.|
|tutorial||Insert a link to an included tutorial file.|
|type||Document the type of an object.|
|@typedef||Document a custom type.|
|@variation||Distinguish different objects with the same name.|
|version||Documents the version number of an item.|
Unsupported JSDoc Tags Unsupported JSDoc Tags
|Tag||Why it’s not supported|
|@virtual||An unsupported synonym. Use @abstract instead.|
|@extends||An unsupported synonym. Use @augments instead.|
|@constructor||An unsupported synonym. Use @class instead.|
|@const||An unsupported synonym. Use @constant instead.|
|@defaultvalue||An unsupported synonym. Use @default instead.|
|@desc||An unsupported synonym. Use @description instead.|
|@host||An unsupported synonym. Use @external instead.|
|@fileoverview||An unsupported synonym. Use @file instead.|
|@overview||An unsupported synonym. Use @file instead.|
|@emits||An unsupported synonym. Use @fires instead.|
|@func||An unsupported synonym. Use @function instead.|
|method||An unsupported synonym. Use @function instead.|
|var||An unsupported synonym. Use @member instead.|
|@emits||An unsupported synonym. Use @fires instead.|
|@arg||An unsupported synonym. Use param instead.|
|@argument||An unsupported synonym. Use param instead.|
|@prop||An unsupported synonym. Use property instead.|
|@returns||An unsupported synonym. Use return instead.|
|@exception||An unsupported synonym. Use @throws instead.|