9.1 JSDoc tag reference

JSDoc serves multiple purposes in JavaScript. In addition to being used togenerate documentation it is also used to control tooling. The best known arethe Closure Compiler type annotations.

9.1.1 Type annotations and other Closure Compiler annotations

Documentation for JSDoc used by the Closure Compiler is described inAnnotating JavaScript for the Closure Compiler and Types in the Closure TypeSystem.

9.1.2 Documentation annotations

In addition to the JSDoc described in Annotating JavaScript for the ClosureCompiler the following tags are common and well supported by variousdocumentation generation tools (such as JsDossier) for purely documentationpurposes.

You may also see other types of JSDoc annotations in third-party code. Theseannotations appear in the JSDoc Toolkit Tag Reference but are not consideredpart of valid Google style.

9.1.2.1 @author or @owner - Not recommended.

Not recommended.

Syntax: @author username@google.com (First Last)

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

Documents the author of a file or the owner of a test, generally only used inthe @fileoverview comment. The @owner tag is used by the unit test dashboardto determine who owns the test results.

9.1.2.2 @bug

Syntax: @bug bugnumber

  1. /** @bug 1234567 */
  2. function testSomething() {
  3.   // …
  4. }
  6. /**
  7.  * @bug 1234568
  8.  * @bug 1234569
  9.  */
  10. function testTwoBugs() {
  11.   // …
  12. }

Indicates what bugs the given test function regression tests.

Multiple bugs should each have their own @bug line, to make searching forregression tests as easy as possible.

9.1.2.3 @code - Deprecated. Do not use.

Deprecated. Do not use. Use Markdown backticks instead.

Syntax: {@code …}

Historically, BatchItem was written as{@code BatchItem}.

  1. /** Processes pending `BatchItem` instances. */
  2. function processBatchItems() {}

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

9.1.2.4 @desc

Syntax: @desc Message description

  1. /** @desc Notifying a user that their account has been created. */
  2. exports.MSG_ACCOUNT_CREATED = goog.getMsg(
  3.     'Your account has been successfully created.');

Syntax: {@link …}

This tag is used to generate cross-reference links within generateddocumentation.

  1. /** Processes pending {@link BatchItem} instances. */
  2. function processBatchItems() {}

Historical note: @link tags have also been used to create external links ingenerated documentation. For external links, always use Markdown's link syntaxinstead:

  1. /**
  2.  * This class implements a useful subset of the
  3.  * [native Event interface](https://dom.spec.whatwg.org/#event).
  4.  */
  5. class ApplicationEvent {}
9.1.2.6 @see

Syntax: @see Link

  1. /**
  2.  * Adds a single item, recklessly.
  3.  * @see #addSafely
  4.  * @see goog.Collect
  5.  * @see goog.RecklessAdder#add
  6.  */

Reference a lookup to another class function or method.

9.1.2.7 @supported

Syntax: @supported Description

  1. /**
  2.  * @fileoverview Event Manager
  3.  * Provides an abstracted interface to the browsers' event systems.
  4.  * @supported IE10+, Chrome, Safari
  5.  */

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

9.1.3 Framework specific annotations

The following annotations are specific to a particular framework.

9.1.3.1 @ngInject for Angular 1
9.1.3.2 @polymerBehavior for Polymer

https://github.com/google/closure-compiler/wiki/Polymer-Pass

9.1.4 Notes about standard Closure Compiler annotations

The following tags used to be standard but are now deprecated.

9.1.4.1 @expose - Deprecated. Do not use.

Deprecated. Do not use. Use @export and/or @nocollapse instead.

9.1.4.2 @inheritDoc - Deprecated. Do not use.

Deprecated. Do not use. Use @override instead.