Comments and annotations

Each plugin and theme that is developed, regardless of language, must be noted. The following examples can be copied in to the relevant position and then altered, as needed.

Syntax

DocBlock (PHP and JavaScript only)

Used to give an overview of what is contained in the file, function, method or class. Whenever possible, all files, functions, methods and classes should contain a header DocBlock, regardless of the contents – this includes files containing only classes.

/**
 *
 *
 */

Note: the opening of the DocBlock comment starts with two asterisks leading on from opening forward slash. All remaining lines indentation needs to be increased by one space, not a tab, to make sure all the asterisks are in a single, vertical line.

Single line comment

For simple, additional descriptions, found throughout the code.

PHP and JavaScript
// Some text inserted here

HTML 
<!-- Some text inserted here -->

Multi-line comment

Used throughout the code where a single line extends, approximately, more than 75 characters

PHP and JavaScript
/*
 * Some text inserted here
 * and some more
 * and some more!
 */

Note: In PHP and JavaScript, drop a line and add a space so the asterixs are all in a single, vertical line

HTML
<!-- 
    Some text inserted here
    And some more 
    And some more!
-->

Note: Tab in comments in HTML when a line is dropped.

File headers

Each file needs to have a DocBlock summarising what can be found in the file including: a summary, description, @package, @subpackage(if applicable) and @since tags.

/**
 * Summary
 *
 * Description
 *
 * @package Plugin_name
 * @subpackage Plugin_name/Folders/Path/File/Is/Located/In
 * @since x.x.x (Version that the file was introduced in)
 */

Classes

Whether it is a main class or a sub class, all classes need to contain a DocBlock, describing the classes function.

Main class

/**
 * Summary
 *
 * Description.
 *
 * @since x.x.x
 */

Sub Class

/**
 * Summary
 *
 * Description.
 *
 * @since x.x.x
 *
 * @see Super_Class
 */

Functions/Methods

Above each function and method, the following annotation should be used to describe what is happening, the parameters passed in to the function and the global variables that are also used from within the applications scope.

/**
 * Summary
 *
 * Description.
 *
 * @since x.x.x 
 * @access (If a method: 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.
 *
 * @global type $var Description.
 *
 * @return type Description.
 */

 

Tag reference table

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.
@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.
@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. Should only be used inline for “linking” hooks.
@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.
@var	datatype description	Data type for a class variable and short description. Callbacks are marked callback.