{"id":175,"date":"2016-08-12T14:47:03","date_gmt":"2016-08-12T13:47:03","guid":{"rendered":"http:\/\/beta.devon.gov.uk\/styleguide\/?page_id=175"},"modified":"2016-08-12T14:47:03","modified_gmt":"2016-08-12T13:47:03","slug":"comments-and-annotations","status":"publish","type":"page","link":"https:\/\/www.devon.gov.uk\/standards\/overview-coding-standards\/comments-and-annotations\/","title":{"rendered":"Comments and annotations"},"content":{"rendered":"

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.<\/p>\n

Syntax<\/h2>\n

DocBlock (PHP and JavaScript only)
\n<\/strong><\/h3>\n

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

\/**\n *\n *\n *\/<\/pre>\n
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<\/strong>, not a tab, to make sure all the asterisks are in a single, vertical line.<\/em><\/p>\n
Single line comment<\/h3>\n
For simple, additional descriptions, found throughout the code.<\/p>\n
PHP and JavaScript\n\/\/ Some\u00a0text\u00a0inserted\u00a0here<\/pre>\n
HTML \n<!-- Some text inserted here --><\/pre>\n
Multi-line comment<\/h3>\n
Used throughout the code where a single line extends, approximately, more than 75 characters<\/p>\n
PHP and JavaScript\n\/*\n * Some text inserted here\n * and some more\n * and some more!\n *\/<\/pre>\n
Note: In PHP and JavaScript, drop a line and add a space so the asterixs are all in a single, vertical line<\/em><\/p>\n
HTML\n<!-- \n    Some text inserted here\n    And some more \n    And some more!\n--><\/pre>\n
Note: Tab in comments in HTML when a line is dropped.<\/em><\/p>\n
File headers<\/h2>\n
Each file needs to have a DocBlock summarising what can be found in the file including: a summary, description, @package<\/code>, @subpackage<\/code>(if applicable) and @since<\/code> tags.<\/p>\n
\/**\n * Summary\n *\n * Description\n *\n * @package Plugin_name\n * @subpackage Plugin_name\/Folders\/Path\/File\/Is\/Located\/In\n * @since x.x.x (Version that the file was introduced in)\n *\/<\/pre>\n
Classes<\/h2>\n
Whether it is a main class or a sub class, all classes need to contain a DocBlock, describing the classes function.<\/p>\n
Main class<\/h3>\n
\/**\n * Summary\n *\n * Description.\n *\n * @since x.x.x\n *\/<\/pre>\n
Sub Class<\/h3>\n
\/**\n * Summary\n *\n * Description.\n *\n * @since x.x.x\n *\n * @see Super_Class\n *\/<\/pre>\n
Functions\/Methods<\/h2>\n
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.<\/p>\n
\/**\n * Summary\n *\n * Description.\n *\n * @since x.x.x \n * @access (If a method: only use if private)\n *\n * @param type  $var Description.\n * @param array $args {\n *     Optional. An array of arguments.\n *\n *     @type type $key Description. Default 'value'. Accepts 'value', 'value'.\n *                     (aligned with Description, if wraps to a new line)\n *     @type type $key Description.\n * }\n * @param type  $var Description.\n *\n * @global type $var Description.\n *\n * @return type Description.\n *\/<\/pre>\n
 <\/p>\n
Tag reference table<\/h2>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Tag<\/th>\nUsage<\/th>\nDescription<\/th>\n<\/tr>\n
@<\/span>access<\/strong><\/td>\npublic
\nprivate
\nprotected<\/td>\n		Indicates access control for a function\/method.
\n@<\/span>access private<\/strong> indicates the function should not be documented.
\nUsed directly below the @<\/span>since<\/strong> line in block.<\/td>\n<\/tr>\n
@<\/span>global<\/strong><\/td>\ntype global
\n$varname
\ndescription<\/td>\n		Document global(s) used in the function\/method. For boolean and integer types, use bool<\/code> and int<\/code>, respectively.<\/td>\n<\/tr>\n
@<\/span>internal<\/strong><\/td>\ninformation string<\/td>\nTypically used for adding notes for internal use only.<\/td>\n<\/tr>\n
@<\/span>ignore<\/strong><\/td>\n(standalone)<\/td>\nUsed to skip parsing of the entire element.<\/td>\n<\/tr>\n
@<\/span>link<\/strong><\/td>\nURL<\/td>\nLink to additional information for the function\/method.
\nFor an external script\/library, links to source.
\nNot to be used for related functions\/methods; use @<\/span>see<\/strong> instead.<\/td>\n<\/tr>\n
@<\/span>method<\/strong><\/td>\nreturntype
\ndescription<\/td>\n		Shows a \u201cmagic<\/a>\u201d method found inside the class.<\/td>\n<\/tr>\n
@<\/span>param<\/strong><\/td>\ndatatype $variable
\ndescription<\/td>\n		Function\/method parameter of the format: parameter type, variable name, description, default behavior. For boolean and integer types, use bool<\/code> and int<\/code>, respectively.<\/td>\n<\/tr>\n
@<\/span>return<\/strong><\/td>\ndatatype description<\/td>\nDocument the return value of functions or methods. @return void<\/code> should not be used outside of the default bundled themes. For boolean and integer types, use bool<\/code> and int<\/code>, respectively.<\/td>\n<\/tr>\n
@<\/span>see<\/strong><\/td>\nelementname<\/td>\nReferences another function\/method\/class the function\/method relies on. Should only be used inline for \u201clinking\u201d hooks.<\/td>\n<\/tr>\n
@<\/span>since<\/strong><\/td>\nversion x.x.x<\/td>\nDocuments release version function\/method was added. Use 3-digit version number \u2013 this is to aid with version searches, and for use when comparing versions in code. Exception is @since MU<\/code>.<\/td>\n<\/tr>\n
@<\/span>subpackage<\/strong><\/td>\nsubpackagename<\/td>\nFor 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.<\/td>\n<\/tr>\n
@<\/span>todo<\/strong><\/td>\ninformation string<\/td>\nDocuments planned changes to an element that have not been implemented.<\/td>\n<\/tr>\n
@<\/span>type<\/strong><\/td>\ndatatype description for an argument array value<\/td>\nUsed to denote argument array value types. See the Hooks<\/strong> or Parameters That Are Arrays<\/strong> sections for example syntax.<\/td>\n<\/tr>\n
@<\/span>var<\/strong><\/td>\ndatatype description<\/td>\nData type for a class variable and short description. Callbacks are marked callback<\/strong>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
<\/p>\n","protected":false},"excerpt":{"rendered":"
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, […]<\/p>\n","protected":false},"author":945,"featured_media":0,"parent":171,"menu_order":2,"comment_status":"closed","ping_status":"closed","template":"","meta":{"_acf_changed":false,"footnotes":"","_links_to":"","_links_to_target":""},"class_list":["post-175","page","type-page","status-publish","hentry"],"acf":[],"publishpress_future_action":{"enabled":false,"date":"2026-06-01 09:09:18","action":"change-status","newStatus":"draft","terms":[],"taxonomy":"","extraData":[]},"publishpress_future_workflow_manual_trigger":{"enabledWorkflows":[]},"_links":{"self":[{"href":"https:\/\/www.devon.gov.uk\/standards\/wp-json\/wp\/v2\/pages\/175","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.devon.gov.uk\/standards\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/www.devon.gov.uk\/standards\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/www.devon.gov.uk\/standards\/wp-json\/wp\/v2\/users\/945"}],"replies":[{"embeddable":true,"href":"https:\/\/www.devon.gov.uk\/standards\/wp-json\/wp\/v2\/comments?post=175"}],"version-history":[{"count":0,"href":"https:\/\/www.devon.gov.uk\/standards\/wp-json\/wp\/v2\/pages\/175\/revisions"}],"up":[{"embeddable":true,"href":"https:\/\/www.devon.gov.uk\/standards\/wp-json\/wp\/v2\/pages\/171"}],"wp:attachment":[{"href":"https:\/\/www.devon.gov.uk\/standards\/wp-json\/wp\/v2\/media?parent=175"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}