メソッドを抽象としてマークします。メソッドを goog.abstractMethod に設定するのと同様に、コンパイラは @abstract アノテーションが付いたメソッドをプルーニングしてコードサイズを縮小できます。

@abstract とマークされたメソッドに空以外の実装がある場合、コンパイラは警告を生成します。

/** @abstract */
foo.MyClass.prototype.abstractMethod = function() {};

変数を読み取り専用としてマークします。コンパイラは、@const 変数をインライン化して、JavaScript コードを最適化できます。

型宣言は省略可能です。

@const とマークされた変数に値が複数回代入されると、コンパイラは警告を生成します。変数がオブジェクトの場合、コンパイラはオブジェクトのプロパティの変更を禁止していません。

/** @const */ var MY_BEER = 'stout';

/**
 * My namespace's favorite kind of beer.
 * @const {string}
 */
mynamespace.MY_BEER = 'stout';

/** @const */ MyClass.MY_BEER = 'stout';

関数をコンストラクタとしてマークします。コンパイラは、new キーワードとともに使用される関数に @constructor アノテーションを必要とします。

例:

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

例:

/** @define {boolean} */
var ENABLE_DEBUG = true;

/** @define {boolean} */
goog.userAgent.ASSUME_IE = false;

関数、メソッド、プロパティをマークします。これにより、使用すべきでないコンパイラ警告が生成されます。

例:

/**
 * 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) {
  ...
};

@dict は、可変長のプロパティを持つオブジェクトの作成に使用されます。コンストラクタ（この例では Foo）に @dict アノテーションが付けられている場合、Foo オブジェクトのプロパティにアクセスするには、角かっこ表記を使用する必要があります。アノテーションは、オブジェクト リテラルで直接使用することもできます。

例:

/**
 * @constructor
 * @dict
 */
function Foo() {}
var obj1 = new Foo();
obj1['x'] = 123;
obj1.x = 234;  // warning

var obj2 = /** @dict */ { 'x': 321 };
obj2.x = 123;  // warning

列挙型の型を指定します。列挙型は、関連する一連の定数をプロパティとして構成するオブジェクトです。@enum タグの後にタイプ式を付ける必要があります。

列挙型の型ラベルは、列挙型の各プロパティに適用されます。たとえば、列挙型の型が number の場合は、列挙された各プロパティを数値にする必要があります。列挙型の型を省略すると、number と見なされます。

例:

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

このコードの場合

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

コンパイラが --generate_exports フラグを指定して実行されると、コードが生成されます。

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

これにより、シンボルがコンパイルされていないコードにエクスポートされます。

/**
 * @export
 * @type {SomeType}
 */

@export アノテーションを使用するコードは、次のいずれかである必要があります。

1. closure/base.js を含む
2. goog.exportSymbol と goog.exportProperty の両方を、同じコードベース内の同じメソッド シグネチャで定義します。

クラスまたはインターフェースを別のクラスから継承するマークを付けます。@extends でマークされたクラスにも、@constructor または @interface のいずれかを指定する必要があります。

注: @extends では、クラスは別のクラスから継承されません。アノテーションは、型チェック中に 1 つのクラスを別のサブクラスとして処理できることをコンパイラに伝えます。

継承の実装例については、Closure Library の関数 goog.inherits() をご覧ください。

例:

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

このクラスを拡張できないことを示します。 メソッドについて、そのメソッドをオーバーライドできるサブクラスがないことを示します。

例:

/**
 * A class that cannot be extended.
 * @final
 * @constructor
 */
sloth.MyFinalClass = function() { ... }

/**
 * A method that cannot be overridden.
 * @final
 */
sloth.MyFinalClass.prototype.method = function() { ... };

@constructor とともに使用され、クラスがインターフェースを実装することを示します。

コンストラクタに @implements のタグを付けてから、インターフェースで定義されたすべてのメソッドとプロパティの実装に失敗すると、コンパイラは警告を生成します。

例:

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

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

このアノテーションは externs プロパティ宣言にのみ表示できます。プロパティには宣言された型がありますが、警告なしで任意の型を割り当てることができます。プロパティにアクセスすると、宣言された型の値が返されます。たとえば、element.innerHTML には任意の型を割り当てることができますが、常に文字列を返します。

/**
 * @type {string}
 * @implicitCast
 */
Element.prototype.innerHTML;

サブクラスのメソッドまたはプロパティがスーパークラスのメソッドまたはプロパティを意図的に非表示にし、まったく同じドキュメントを持っていることを示します。@inheritDoc タグは @override タグを示します。

例:

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

関数をインターフェースとしてマークする。インターフェースには、型に必要なメンバーを指定します。インターフェースを実装するクラスは、そのインターフェースのプロトタイプで定義されているすべてのメソッドとプロパティを実装する必要があります。詳細については、@implements をご覧ください。

コンパイラは、インターフェースがインスタンス化されていないことを確認します。new キーワードがインターフェース関数とともに使用されている場合、コンパイラは警告を生成します。

例:

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

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

オブジェクト リテラルのキーは、他のオブジェクトのプロパティとして扱う必要があります。このアノテーションは、オブジェクト リテラルにのみ表示されます。

中かっこ内の名前は、他のアノテーションのような型名ではありません。オブジェクト名です。このプロパティは、プロパティが貸し出されるオブジェクトの名前を指定します。たとえば、@type {Foo} は「Foo のインスタンス」を意味しますが、@lends {Foo} は「コンストラクタ Foo」を意味します。

このアノテーションについて詳しくは、JSDoc Toolkit ドキュメントをご覧ください。

例:

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

マークされたファイルのコンパイル済みコードの前に、関連するコメントを挿入するようにコンパイラに指示します。このアノテーションを使用すると、コンパイル時の変更後も重要な通知（法的ライセンスや著作権テキストなど）を通知できます。改行は保持されます。

例:

/**
 * @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:
 */

コンパイラが変数に折りたたむべきではないプロパティを示します。@nocollapse の主な用途は、変更可能なプロパティのエクスポートを可能にすることです。なお、折りたたまれていないプロパティの名前もコンパイラで変更できます。 オブジェクトであるプロパティに @nocollapse アノテーションを付けると、そのプロパティはすべて折りたたまれていないままになります。

例:

/**
 * A namespace.
 * @const
 */
var foo = {};

/**
 * @nocollapse
 */
foo.bar = 42;

window['foobar'] = foo.bar;

宣言された外部関数の呼び出しに副作用がないことを示します。このアノテーションを使用すると、戻り値が使用されていない場合、コンパイラは関数の呼び出しを削除できます。アノテーションは extern files でのみ使用できます。

例:

/** @nosideeffects */
function noSideEffectsFn1() {}

/** @nosideeffects */
var noSideEffectsFn2 = function() {};

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

サブクラスのメソッドまたはプロパティがスーパークラスのメソッドまたはプロパティを意図的に非表示にすることを示します。他のアノテーションが含まれていない場合、メソッドまたはプロパティは自動的にスーパークラスからアノテーションを継承します。

例:

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

メンバーまたはプロパティを非公開としてマークします。同じディレクトリ内のコードのみが、@package とマークされた名前にアクセスできます。特に、親ディレクトリと子ディレクトリ内のコードは、@package とマークされた名前にアクセスできません。

パブリック コンストラクタには、@package プロパティを持つことで、ディレクトリ外の呼び出し元が使用できるメソッドを制限できます。一方、@package コンストラクタは、パブリック プロパティを持つことで、ディレクトリ外の呼び出し元が型を直接インスタンス化できないようにします。

例:

/**
 * Returns the window object the foreign document resides in.
 *
 * @return {Object} The window object of the peer.
 * @package
 */
goog.net.xpc.CrossPageChannel.prototype.getPeerWindowObject = function() {
  // ...
};

関数の引数のタイプを指定するために、メソッド、関数、コンストラクタの定義で使用されます。@param タグは、関数定義のパラメータと同じ順序にする必要があります。

@param タグの後にタイプ式を付ける必要があります。

または、パラメータの型をインラインでアノテーションすることもできます（この例では foo 関数をご覧ください）。

例:

/**
 * 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) {
  ...
};

function foo(/** number */ a, /** number */ b) {
  return a - b + 1;
}

/**
 * @param {{name: string, age: number}} person
 */
function logPerson({name, age}) {
  console.log(`${name} is ${age} years old`);
}

メンバーを非公開に設定する。同じファイル内のコードのみが、@private とマークされたグローバル変数と関数にアクセスできます。@private としてマークされたコンストラクタは、同じファイル内のコードによって、またその静的メンバーとインスタンス メンバーによってのみインスタンス化できます。

@private としてマークされたコンストラクタのパブリック静的プロパティにも、どこからでもアクセスでき、instanceof 演算子でいつでも @private メンバーにアクセスできます。

例:

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

メンバーまたはプロパティが保護されることを示します。

@protected としてマークされたプロパティは、以下にアクセスできます。

• 同じファイル内のすべてのコード
• 静的メソッド、プロパティが定義されているクラスのサブクラスのインスタンス インスタンス。

例:

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

関数を構造インターフェースとしてマークします。構造インターフェースは名詞 @interface に似ていますが、暗黙的な実装が可能です。つまり、構造インターフェースのプロトコルで定義されるメソッドとプロパティを含むすべてのクラスが、@implements タグを使用するかどうかにかかわらず、構造インターフェースを実装するということです。 レコード型とオブジェクト リテラルには、必要なプロパティが含まれている場合に、構造インターフェースが暗黙的に実装されます。

例:

/**
 * Anything with a draw() method.
 * @record
 */
function Drawable() {};
Drawable.prototype.draw = function() {};

/**
 * A polygon.
 * @param {!Drawable} x
 */
function render(x) { x.draw(); };

var o = { draw() { /* ... */ } };
render(o);

メソッドと関数の定義の戻り値の型を指定します。 @return タグの後にタイプ式を付ける必要があります。

あるいは、戻り値の型にアノテーションを付けることもできます（この例の関数 foo をご覧ください）。

外部にない関数に戻り値がない場合、@return タグを省略できます。コンパイラは関数が undefined を返すと想定します。

例:

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

function /** number */ foo(x) { return x - 1; }

@struct は、固定の数のプロパティを持つオブジェクトの作成に使用されます。コンストラクタ（この例では Foo）に @struct アノテーションを付けると、ドット表記を使用して角かっこ表記ではなく、Foo オブジェクトのプロパティにアクセスできます。また、作成後に Foo インスタンスにプロパティを追加することはできません。アノテーションは、オブジェクト リテラルで直接使用することもできます。

例:

/**
 * @constructor
 * @struct
 */
function Foo(x) {
  this.x = x;
}
var obj1 = new Foo(123);
var someVar = obj1.x;  // OK
obj1.x = "qwerty";  // OK
obj1['x'] = "asdf";  // warning
obj1.y = 5;  // warning

var obj2 = /** @struct */ { x: 321 };
obj2['x'] = 123;  // warning

汎用型をご覧ください。

例:

/**
 * @param {T} t
 * @constructor
 * @template T
 */
Container = function(t) { ... };

関数内で、キーワード this が参照するオブジェクトのタイプを指定します。@this タグの後にタイプ式を付ける必要があります。

コンパイラ警告を防ぐには、プロトタイプ メソッドでも @constructor とマークされた関数でもない関数に this が出現するたびに、@this アノテーションを使用する必要があります。

例:

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

関数からスローされた例外を文書化するために使用されます。 タイプ チェッカーは現在、この情報を使用しません。 これは、外部ファイルで宣言された関数に副作用があるかどうかを判断するためにのみ使用されます。

例:

/**
 * @throws {DOMException}
 */
DOMApplicationCache.prototype.swapCache = function() { ... };

変数、プロパティ、式のタイプを示します。@type タグの後にタイプ式を付ける必要があります。

変数または関数のパラメータを宣言する場合、2 番目の例のように、{} と @type を省略して型アノテーションをインラインで記述できます。このショートカットは、変数または関数パラメータが宣言されている場合にのみ実行できます。後で型を調整する場合は、型キャストが必要になります。

例:

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

var /** string */ name = 'Jamie';
function useSomething(/** (string|number|!Object) */ something) {
...
}

より複雑な型のエイリアスを宣言します。現在、typedef は関数内ではなく、トップレベルでのみ定義できます。新しい型推論でこの制限を修正しました。

例:

/** @typedef {(string|number)} */
goog.NumberLike;

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

クラスが @struct 型でも @dict 型でもないことを示します。通常はこれがデフォルトであるため、通常は明示的に記述する必要はありません。ただし、goog.defineClass または class キーワードを使用している場合は、デフォルトで @struct になるクラスが生成されます。

例:

/**
 * @constructor
 * @unrestricted
 */
function Foo(x) {
  this.x = x;
}
var obj1 = new Foo(123);
var someVar = obj1.x;  // OK
obj1.x = "qwerty";  // OK
obj1['x'] = "asdf";  // OK
obj1.y = 5;  // OK