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

TagUsageDescription
@accesspublic
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.
@globaltype global
$varname
description
Document global(s) used in the function/method. For boolean and integer types, use bool and int, respectively.
@internalinformation stringTypically used for adding notes for internal use only.
@ignore(standalone)Used to skip parsing of the entire element.
@linkURLLink 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.
@methodreturntype
description
Shows a “magic” method found inside the class.
@paramdatatype $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.
@returndatatype descriptionDocument 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.
@seeelementnameReferences another function/method/class the function/method relies on. Should only be used inline for “linking” hooks.
@sinceversion x.x.xDocuments 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.
@subpackagesubpackagenameFor 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.
@todoinformation stringDocuments planned changes to an element that have not been implemented.
@typedatatype description for an argument array valueUsed to denote argument array value types. See the Hooks or Parameters That Are Arrays sections for example syntax.
@vardatatype descriptionData type for a class variable and short description. Callbacks are marked callback.