(original) (raw)

@author

@author username@google.com (first last)

For example:

/** * @fileoverview Utilities for handling textareas. * @author kuth@google.com (Uthur Pendragon) */

Document the author of a file or the owner of a test, generally only used in the @fileoverview comment.

@code

{@code ...}

For example:

/** * Moves to the next position in the selection. * Throws {@code goog.iter.StopIteration} when it * passes the end of the range. * @return {Node} The node at the next position. */ goog.dom.RangeIterator.prototype.next = function() { // ... };

Indicates that a term in a JSDoc description is code so it may be correctly formatted in generated documentation.

@const

@const
@const {type}

For example:

/** @const */ var MY_BEER = 'stout'; /** * My namespace's favorite kind of beer. * @const {string} */ mynamespace.MY_BEER = 'stout'; /** @const */ MyClass.MY_BEER = 'stout'; /** * Initializes the request. * @const */ mynamespace.Request.prototype.initialize = function() { // This method cannot be overridden in a subclass. };

Marks a variable (or property) as read-only and suitable for inlining.

A @const variable is an immutable pointer to a value. If a variable or property marked as@const is overwritten, JSCompiler will give warnings.

The type declaration of a constant value can be omitted if it can be clearly inferred. An additional comment about the variable is optional.

When @const is applied to a method, it implies the method is not only not overwritable, but also that the method is finalized — not overridable in subclasses.

For more on @const, see theConstants section.

@constructor

@constructor

For example:

/** * A rectangle. * @constructor */ function GM_Rect() { ... }

Used in a class's documentation to indicate the constructor.

@define

@define {Type} description

For example:

/** @define {boolean} */ var TR_FLAGS_ENABLE_DEBUG = true; /** * @define {boolean} Whether we know at compile-time that * the browser is IE. */ goog.userAgent.ASSUME_IE = false;

Indicates a constant that can be overridden by the compiler at compile-time. In the example, the compiler flag--define='goog.userAgent.ASSUME_IE=true' could be specified in the BUILD file to indicate that the constant goog.userAgent.ASSUME_IE should be replaced with true.

@deprecated

@deprecated Description

For example:

/** * Determines whether a node is a field. * @return {boolean} True if the contents of * the element are editable, but the element * itself is not. * @deprecated Use isField(). */ BN_EditUtil.isTopEditableField = function(node) { // ... };

Used to tell that a function, method or property should not be used any more. Always provide instructions on what callers should use instead.

@dict

@dict Description

For example:

/** * @constructor * @dict */ function Foo(x) { this['x'] = x; } var obj = new Foo(123); var num = obj.x; // warning (/** @dict */ { x: 1 }).x = 123; // warning

When a constructor (Foo in the example) is annotated with @dict, you can only use the bracket notation to access the properties of Foo objects. The annotation can also be used directly on object literals.

@enum

@enum {Type}

For example:

/** * Enum for tri-state values. * @enum {number} */ project.TriState = { TRUE: 1, FALSE: -1, MAYBE: 0 };

@export

@export

For example:

/** @export */ foo.MyPublicClass.prototype.myPublicMethod = function() { // ... };

Given the code on the left, when the compiler is run with the --generate_exports flag, it will generate the code:

goog.exportSymbol('foo.MyPublicClass.prototype.myPublicMethod', foo.MyPublicClass.prototype.myPublicMethod);

which will export the symbols to uncompiled code. Code that uses the @export annotation must either

1. include //javascript/closure/base.js, or
2. define both goog.exportSymbol andgoog.exportProperty with the same method signature in their own codebase.

@expose

@expose

For example:

/** @expose */ MyClass.prototype.exposedProperty = 3;

Declares an exposed property. Exposed properties will not be removed, or renamed, or collapsed, or optimized in any way by the compiler. No properties with the same name will be able to be optimized either.

@expose should never be used in library code, because it will prevent that property from ever getting removed.

@extends

@extends Type @extends {Type}

For example:

/** * Immutable empty node list. * @constructor * @extends goog.ds.BasicNodeList */ goog.ds.EmptyNodeList = function() { ... };

Used with @constructor to indicate that a class inherits from another class. Curly braces around the type are optional.

@externs

@externs

For example:

/** * @fileoverview This is an externs file. * @externs */ var document;

Declares an externs file.

@fileoverview

@fileoverview Description

For example:

/** * @fileoverview Utilities for doing things that require this very long * but not indented comment. * @author kuth@google.com (Uthur Pendragon) */

Makes the comment block provide file level information.

@implements

@implements Type @implements {Type}

For example:

/** * A shape. * @interface */ function Shape() {}; Shape.prototype.draw = function() {}; /** * @constructor * @implements {Shape} */ function Square() {}; Square.prototype.draw = function() { ... };

Used with @constructor to indicate that a class implements an interface. Curly braces around the type are optional.

@inheritDoc

@inheritDoc

For example:

/** @inheritDoc */ project.SubClass.prototype.toString() { // ... };

Deprecated. Use@override instead.

Indicates that a method or property of a subclass intentionally hides a method or property of the superclass, and has exactly the same documentation. Notice that@inheritDoc implies @override

@interface

@interface

For example:

/** * A shape. * @interface */ function Shape() {}; Shape.prototype.draw = function() {}; /** * A polygon. * @interface * @extends {Shape} */ function Polygon() {}; Polygon.prototype.getSides = function() {};

Used to indicate that the function defines an interface.

@lends

@lends objectName
@lends {objectName}

For example:

goog.object.extend( Button.prototype, /** @lends {Button.prototype} */ { isButton: function() { return true; } });

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.

Notice 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".

The JSDoc Toolkit docs have more information on this annotation.

@license or@preserve

@license Description

For example:

/** * @preserve Copyright 2009 SomeThirdParty. * Here is the full license text and copyright * notice for this file. Note that the notice can span several * lines and is only terminated by the closing star and slash: */

Anything marked by @license or@preserve will be retained by the compiler and output at the top of the compiled code for that file. This annotation allows important notices (such as legal licenses or copyright text) to survive compilation unchanged. Line breaks are preserved.

@noalias

@noalias

For example:

/** @noalias */ function Range() {}

Used in an externs file to indicate to the compiler that the variable or function should not be aliased as part of the alias externals pass of the compiler.

@nocompile

@nocompile

For example:

/** @nocompile */ // JavaScript code

Used at the top of a file to tell the compiler to parse this file but not compile it. Code that is not meant for compilation and should be omitted from compilation tests (such as bootstrap code) uses this annotation. Use sparingly.

@nosideeffects

@nosideeffects

For example:

/** @nosideeffects */ function noSideEffectsFn1() { // ... } /** @nosideeffects */ var noSideEffectsFn2 = function() { // ... }; /** @nosideeffects */ a.prototype.noSideEffectsFn3 = function() { // ... };

This annotation can be used as part of function and constructor declarations to indicate that calls to the declared function have no side-effects. This annotation allows the compiler to remove calls to these functions if the return value is not used.

@override

@override

For example:

/** * @return {string} Human-readable representation of project.SubClass. * @override */ project.SubClass.prototype.toString = function() { // ... };

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.

@param

@param {Type} varname Description

For example:

/** * Queries a Baz for items. * @param {number} groupNum Subgroup id to query. * @param {string|number|null} term An itemName, * or itemId, or null to search everything. */ goog.Baz.prototype.query = function(groupNum, term) { // ... };

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.

@private

@private
@private {type}

For example:

/** * Handlers that are listening to this logger. * @private {!Array.} */ this.handlers_ = [];

Used in conjunction with a trailing underscore on the method or property name to indicate that the member isprivate and final.

@protected

@protected
@protected {type}

For example:

/** * Sets the component's root element to the given element. * @param {Element} element Root element for the component. * @protected */ goog.ui.Component.prototype.setElementInternal = function(element) { // ... };

Used to indicate that the member or property isprotected. Should be used in conjunction with names with no trailing underscore.

@public

@public
@public {type}

For example:

/** * Whether to cancel the event in internal capture/bubble processing. * @public {boolean} * @suppress {visibility} Referencing this outside this package is strongly * discouraged. */ goog.events.Event.prototype.propagationStopped_ = false;

Used to indicate that the member or property is public. Variables and properties are public by default, so this annotation is rarely necessary. Should only be used in legacy code that cannot be easily changed to override the visibility of members that were named as private variables.

@return

@return {Type} Description

For example:

/** * @return {string} The hex ID of the last item. */ goog.Baz.prototype.getLastId = function() { // ... return id; };

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.

@see

@see Link

For example:

/** * Adds a single item, recklessly. * @see #addSafely * @see goog.Collect * @see goog.RecklessAdder#add ...

Reference a lookup to another class function or method.

@struct

@struct Description

For example:

/** * @constructor * @struct */ function Foo(x) { this.x = x; } var obj = new Foo(123); var num = obj['x']; // warning obj.y = "asdf"; // warning Foo.prototype = /** @struct */ { method1: function() {} }; Foo.prototype.method2 = function() {}; // warning

When a constructor (Foo in the example) is annotated with @struct, you can only use the dot notation to access the properties of Foo objects. Also, you cannot add new properties to Foo objects after they have been created. The annotation can also be used directly on object literals.

@supported

@supported Description

For example:

/** * @fileoverview Event Manager * Provides an abstracted interface to the * browsers' event systems. * @supported So far tested in IE6 and FF1.5 */

Used in a fileoverview to indicate what browsers are supported by the file.

@suppress

@suppress {warning1|warning2} @suppress {warning1,warning2}

For example:

/** * @suppress {deprecated} */ function f() { deprecatedVersionOfF(); }

Suppresses warnings from tools. Warning categories are separated by | or ,.

@template

@template

For example:

/** * @param {function(this:T, ...)} fn * @param {T} thisObj * @param {...*} var_args * @template T */ goog.bind = function(fn, thisObj, var_args) { ... };

This annotation can be used to declare atemplate typename.

@this

@this Type @this {Type}

For example:

pinto.chat.RosterWidget.extern('getRosterElement', /** * Returns the roster widget element. * @this pinto.chat.RosterWidget * @return {Element} */ function() { return this.getWrappedComponent_().getElement(); });

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.

@type

@type Type @type {Type}

For example:

/** * The message hex ID. * @type {string} */ var hexId = hexId;

Identifies the type of a variable, property, or expression. Curly braces are not required around most types, but some projects mandate them for all types, for consistency.

@typedef

@typedef

For example:

/** @typedef {(string|number)} */ goog.NumberLike; /** @param {goog.NumberLike} x A number or a string. */ goog.readNumber = function(x) { ... }

This annotation can be used to declare an alias of a morecomplex type.