JavaScript DocBlock standard
To add JavaScript code inline documentation, follow these guidelines. Some parts of the code may not comply with this standard, but we are working to gradually improve this. Following these standard is optional for third-party developers, but will help to create consistent, clean, and easy to read inline documentation. This standard are a subset of Google JavaScript Style Guide regulations.
Use RFC 2119 to interpret the "must," "must not," "required," "shall," "shall not," "should," "should not," "recommended," "may," and "optional" keywords.
Use JSDoc#
Document all files, classes, methods, and properties with JSDoc comments.
Inline comments should be of the "//" type.
It is recommended to avoid sentence fragments in documentation blocks. Use sentence-style capitalization and put a period at the end. Sentence fragmentation is acceptable in inline commentaries to keep it short.
Comment syntax#
JSDoc comments requirements:
- A JSDoc comment should begin with a slash (/) and two asterisks (*).
- Inline tags should be enclosed in braces:
{ @code this }
. @desc
Block tags should always start on their own line.
Example:
Copied to your clipboard1/**2* A testJSDoc comment should begin with a slash and 2 asterisks.3* Inline tags should be enclosed in braces like {@code this}.4* @desc Block tags should always start on their own line.5*/
Many tools extract metadata from JSDoc comments to validate and optimize the code.
JSDoc indentation#
If you have to line break a block tag, you should treat this as breaking a code statement and indent it four spaces.
Copied to your clipboard1/**2 * Illustrates line wrapping for long param/return descriptions.3 *4 * @param {string} foo This is a param with a description too long to fit in5 * one line.6 * @return {number} This returns something that has a description too long to7 * fit in one line.8 */9project.MyClass.prototype.method = function(foo) {10 return 5;11};
Class comments#
Classes must be documented with a description, and appropriate type tags.
Copied to your clipboard1/**2 * Class making something fun and easy.3 * @param {string} arg1 An argument that makes this more interesting.4 * @param {Array.<number>} arg2 List of numbers to be processed.5 * @constructor6 */7project.MyClass = function(arg1, arg2) {8 // ...9};
Method and function comments#
A description must be provided along with parameters. Method descriptions should start with a sentence written in the third person declarative voice.
Copied to your clipboard1/**2 * Operates on an instance of MyClass and returns something.3 *4 * @param {project.MyClass} obj Instance of MyClass which leads to a long5 * comment that needs to be wrapped to two lines.6 * @return {boolean} Whether something occurred.7 */8function someMethod(obj) {9 // ...10}
Property comments#
Copied to your clipboard1/**2 * Maximum number of things per pane.3 *4 * @type {number}5 */6project.MyClass.prototype.someProperty = 4;
JSDoc tag reference#
@const#
Marks a variable read-only and suitable for inlining. Generates warnings if it is rewritten. Constants should also be ALL_CAPS, but the annotation should help eliminate reliance on the naming convention.
Copied to your clipboard1/** @const */ var DEFAULT_TIMEZONE = 'GMT';23/** @const */ MyClass.DEFAULT_TIMEZONE = 'GMT';45/**6 * My namespace's default timezone.7 *8 * @const9 * @type {string}10 */11mynamespace.DEFAULT_TIMEZONE = 'GMT';
@extends#
Used with @constructor
to indicate that a class inherits from another class.
Copied to your clipboard1/**2 * Immutable empty node list.3 *4 * @constructor5 * @extends project.MyClass.BasicNodeList6 */7project.MyClass.EmptyNodeList = function() {8 // ...9};
@interface#
Used to indicate that the function defines an interface.
Copied to your clipboard1/**2 * A shape.3 *4 * @interface5 */6function Shape() {};7Shape.prototype.draw = function() {};89/**10 * A polygon.11 *12 * @interface13 * @extends {Shape}14 */15function Polygon() {};16Polygon.prototype.getSides = function() {};
@implements#
Used with @constructor
to indicate that a class implements an interface.
Copied to your clipboard1/**2 * A shape.3 *4 * @interface5 */6function Shape() {};7Shape.prototype.draw = function() {};89/**10 * @constructor11 * @implements {Shape}12 */13function Square() {};14Square.prototype.draw = function() {15 // ...16};
@lends#
Indicates that the keys of an object literal should be treated as properties of some other object. This annotation should only appear on object literals.
Please note that the name in braces is not a type name like in other annotations. It's an object name. It names the object on which the properties are "lent". For example, @type {Foo}
means "an instance of Foo," but @lends {Foo}
means "the constructor Foo".
Please refer to JSDoc Toolkit for more information about this annotation.
Copied to your clipboard1project.MyClass.extend(2 Button.prototype,3 /** @lends {Button.prototype} */ {4 isButton: function() {return true;}5 }6);
@override#
Indicates that a method or property of a subclass intentionally hides a method or property of the superclass. If no other documentation is included, the method or property also inherits documentation from its superclass.
Copied to your clipboard1/**2 * @return {string} Human-readable representation of project.SubClass.3 * @override4 */5project.SubClass.prototype.toString() {6 // ...7};
@param#
Used with method, function and constructor calls to document the arguments of a function.
Type names must be enclosed in curly braces. If the type is omitted, the compiler will not type-check the parameter.
Copied to your clipboard1/**2 * Queries a Storage for items.3 *4 * @param {number} groupNum Subgroup id to query.5 * @param {string|number|null} term An itemName,6 * or itemId, or null to search everything.7 */8[namespace](https://glossary.magento.com/namespace).Storage.prototype.query = function(groupNum, term) {9 // ...10};
@return#
Used with method and function calls to document the return type. When writing descriptions for boolean parameters, prefer "Whether the component is visible" to "True if the component is visible, false otherwise". If there is no return value, do not use an @return
tag.
Type names must be enclosed in curly braces. If the type is omitted, the compiler will not type-check the return value.
Copied to your clipboard1/**2 * @return {string} The hex ID of the last item.3 */4namespace.Storage.prototype.getLastId = function() {5 // ...6 return id;7};
@this#
The type of the object in whose context a particular method is called. Required when the this keyword is referenced from a function that is not a prototype method.
Copied to your clipboard1pinto.chat.RosterWidget.extern('getRosterElement',2 /**3 * Returns the roster widget element.4 *5 * @this pinto.chat.RosterWidget6 * @return {Element}7 */8 function() {9 return this._getWrappedComponent().getElement();10 }11);
@type#
Identifies the type of a variable, property, or expression.
Copied to your clipboard1/**2 * The message hex ID.3 *4 * @type {string}5 */6var hexId = hexId;
@typedef#
This annotation can be used to declare an alias of a more complex type.
Copied to your clipboard1/** @typedef {(string|number)} */2namespace.NumberLike;34/** @param {namespace.NumberLike} x A number or a string. */5namespace.readNumber = function(x) {6 // ...7}
JavaScript types#
number#
Copied to your clipboard1121.03-541e55Math.PI
Number#
Number object.
Copied to your clipboardnew Number(true)
string#
String value.
Copied to your clipboard1'Hello'2"World"3String(42)
String#
String object.
Copied to your clipboard1new String('Hello')2new String(42)
boolean#
Boolean value.
Copied to your clipboard1true2false3Boolean(0)
Boolean#
Boolean object.
Copied to your clipboardnew Boolean(true)
RegExp#
Copied to your clipboard1new RegExp('hello')2/world/g
Date#
Copied to your clipboard1new Date2new Date()
null#
Copied to your clipboardnull
undefined#
Copied to your clipboardundefined
void#
No return value.
Copied to your clipboard1function f() {2 return;3}
Array#
Untyped array.
Copied to your clipboard1['foo', 0.3, null]2[]
Array.<number>#
An array of numbers.
Copied to your clipboard[11, 22, 33]
Array.<Array.<string>>#
Array of arrays of strings.
Copied to your clipboard[['one', 'two', 'three'], ['foo', 'bar']]
Object#
Copied to your clipboard1{}2{foo: 'abc', bar: 123, baz: null}
Object.<string>#
An object. In the object, the values are strings.
Copied to your clipboard{'foo': 'bar'}
Object.<number,string>#
An object. In the object, the keys are numbers and the values are strings. Note that in JavaScript, the keys are always implicitly converted to strings, so obj['1'] == obj[1]. So the key will always be a string in for...in loops. But the compiler will verify the type if the key when indexing into the object.
Copied to your clipboard1var obj = {};2obj[1] = 'bar';
Function#
Function object
Copied to your clipboard1function(x, y) {2 return x * y;3}
function(number, number): number#
Function value
Copied to your clipboard1function(x, y) {2 return x * y;3}
SomeClass#
Copied to your clipboard1/** @constructor */2function SomeClass() {}34new SomeClass();
SomeInterface#
Copied to your clipboard1/** @interface */2function SomeInterface() {}34SomeInterface.prototype.draw = function() {};
project.MyClass#
Copied to your clipboard1/** @constructor */2project.MyClass = function () {}34new project.MyClass()
Element#
Elements in the DOM.
Copied to your clipboarddocument.createElement('div')
Node#
Node in the DOM.
Copied to your clipboarddocument.body.firstChild
HTMLInputElement#
A specific type of DOM element.
Copied to your clipboardhtmlDocument.getElementsByTagName('input')[0]
JavaScript type language#
Type name#
Simply the name of a type.
Copied to your clipboard{boolean}, {Window}, {namespace.ui.Menu}
Type application#
Parametrizes a type, by applying a set of type arguments to that type. The idea is analogous to generics in Java.
Copied to your clipboard1// An array of strings.2{Array. <string>}34// An object. In the object, the keys are strings and the values are numbers.5{Object. }
Type union#
Indicates that a value might have type A OR type B.
Copied to your clipboard1// A number or a boolean.2{(number|boolean)}
Deprecated syntaxes:
Copied to your clipboard{(number,boolean)}, {number|boolean}, {(number||boolean)}
Record type#
Indicates that the value has the specified members with the specified types. In this case, myNum
with a type number
and myObject
with any type. Note that the braces are part of the type syntax. For example, to denote an Array
of objects that have a length
property, you might write Array.<{length}>
.
Copied to your clipboard1// An anonymous type with the given type members.2codemyNum: number, myObject}}
Nullable type#
Indicates that a value is type A or null
. By default, all object types are nullable.
Function types are not nullable.
Copied to your clipboard1// A number or NULL.2{?number}
Deprecated syntax:
Copied to your clipboard{number?}
Non-nullable type#
Indicates that a value is type A and not null. By default, all value types (boolean, number, string, and undefined) are not nullable.
Copied to your clipboard1// An Object, but never the null value.2{!Object}
Deprecated syntax:
Copied to your clipboard{Object!}
Function type#
Specifies a function.
Copied to your clipboard1// A function that takes two arguments (a string and a boolean), and has an unknown return value.2{function(string, boolean)}
Function return type#
Specifies a function return type.
Copied to your clipboard1// A function that takes no arguments and returns a number.2{function(): number}
Function this
type#
Specifies the context type of a function type.
Copied to your clipboard1// A function that takes one argument (a string), and executes in the context of a namespace.ui.Menu.2{function(this:namespace.ui.Menu, string)}
Function new
type#
Specifies the constructed type of a constructor.
Copied to your clipboard1// A constructor that takes one argument (a string), and creates a new instance of namespace.ui.Menu when called with the 'new' keyword.2{function(new:namespace.ui.Menu, string)}
Variable arguments#
Specifies variable arguments to a function.
Copied to your clipboard1// A function that takes one argument (a string), and then a variable number of arguments that must be numbers.2{function(string, ...[number]): number}
Variable arguments (in @param
annotations)#
Specifies that the annotated function accepts a variable number of arguments.
Copied to your clipboard1// A variable number of arguments to an annotated function.2@param {...number} var_args
Functional optional arguments#
Specifies optional arguments to a function.
Copied to your clipboard1// A function that takes one optional, nullable string and one optional number as arguments. The = syntax is only for function type declarations.2{function(?string=, number=)}
Functional optional arguments (in @param
annotations)#
Specifies that the annotated function accepts an optional argument.
Copied to your clipboard1// An optional parameter of type number.2@param {number=} opt_argument
The ALL type#
Indicates that the variable can take on any type.
Copied to your clipboard{*}
The UNKOWN type#
Indicates that the variable can take on any type, and the compiler should not type-check any uses of it.
Copied to your clipboard{?}