Annotations used in JSDoc

Tag Description
@author Developer's name
@constructor Marks a function as a constructor
@deprecated Marks a method as deprecated
@exception Synonym for @throws
@param Documents a method parameter; a datatype indicator can be added between curly braces
@private Signifies that a method is private
@return Documents a return value
@see Documents an association to another object
@this Specifies the type of the object to which the keyword "this" refers within a function.
@throws Documents an exception thrown by a method
@version Provides the version number of a library

 

JSDocタグリファレンス

タグ 書式と例 説明
@author
@author メールアドレス (名 姓)

例：
/**
 * @fileoverview テキストエリアを扱うためのユーティリティ群。
 * @author kuth@google.com (Uthur Pendragon)
 */
 ファイルの著者、またはテストの所有者を記載します。通常 @fileoverview を含むコメントの中でのみ使用されます。
@code
{@code ...}

例：
/**
 * 選択されたものの中で次の位置に移動します。
 * Throws {@code goog.iter.StopIteration} 最後尾を
 *    超えた場合に発生する。
 * @return {Node} 次の位置のノード。
 */
goog.dom.RangeIterator.prototype.next = function() {
  // ...
};
 JSDocの説明文に含まれる語句がコードであることを示します。生成されたドキュメント内で適切に整形されることが想定されています。
@const
@const

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

/**
 * 名前空間が好きなビールの種類
 * @const
 * @type {string}
 */
mynamespace.MY_BEER = 'stout';

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

/**
 * リクエストを初期化します。
 * @const
 */
mynamespace.Request.prototype.initialize = function() {
  // サブクラスはこのメソッドをオーバーライドできません。
}
 変数（またはプロパティ）が読み取り専用であることを示します。このタグはインラインで記述するのに向いています。

@const が付けられた変数はある値への固定された参照と見なされ、 @const 付きの変数やプロパティが上書きされているとCompilerは警告を出力します。

データ型を明確に推測できるのであれば型の宣言は省いてもかまいません。その他のコメントの追加も必須ではありません。

メソッドに @const が付けられている場合、そのメソッドに対しては単に上書きだけでなく、サブクラスによるオーバーライドも禁止されていることを意味します。

@const のより詳細な説明は「定数」を参照してください。
@constructor
@constructor

例：
/**
 * 長方形。
 * @constructor
 */
function GM_Rect() {
  ...
}
 クラスの説明の中で使い、関数がコンストラクタであることを示します。
@define
@define {型名} 説明文

例：
/** @define {boolean} */
var TR_FLAGS_ENABLE_DEBUG = true;
/** @define {boolean} */
goog.userAgent.ASSUME_IE = false;
 コンパイル時にCompilerによって上書きされる定数であることを示します。左の例でコンパイルフラグに --define='goog.userAgent.ASSUME_IE=true' と指定すると、ビルド後のファイルでは goog.userAgent.ASSUME_IE の値はtrueに置き換えられます。
@deprecated
@deprecated 説明文

例：
/**
 * ノードがフィールドかどうかを判定します。
 * @return {boolean} 要素の内容が
 *     編集可能ならtrue。ただし要素そのものは
 *     編集不可。
 * @deprecated isField() を使ってください。
 */
BN_EditUtil.isTopEditableField = function(node) {
  // ...
};
 関数、メソッド、プロパティをこれ以上使うべきでないことを伝えます。説明文の中でそれに替わるものを指示するのが普通です。
@dict
@dict 説明文

例：
/**
 * @constructor
 * @dict
 */
function Foo(x) {
  this['x'] = x;
}
var obj = new Foo(123);
var num = obj.x;  // 警告

(/** @dict */ { x: 1 }).x = 123;  // 警告
 コンストラクタ（左の例の Foo ）に @dict が付けられた場合、 Foo オブジェクトのプロパティへのアクセスは角括弧による表記法でのみ可能となります。アノテーションをオブジェクトリテラルに直接記述することもできます。
@enum
@enum {型名}

例：
/**
 * 3つの状態を値にもつ列挙型。
 * @enum {number}
 */
project.TriState = {
  TRUE: 1,
  FALSE: -1,
  MAYBE: 0
};
@export
@export

例：
/** @export */
foo.MyPublicClass.prototype.myPublicMethod = function() {
  // ...
};
 --generate_exports フラグを付けてコンパイルを実行すると、左のコードは次のように出力されます:

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

コンパイル前のシンボルがエクスポートされているのが分かります。 @export を使用するには以下の条件のどちらかを満たしていなければなりません。

1. //javascript/closure/base.js をインクルードしている
2. コードベース内に goog.exportSymbol と goog.exportProperty の両方が同じメソッドシグネチャで存在している。
@expose
@expose

例：
/** @export */
MyClass.prototype.exposedProperty = 3;
 外部公開されているプロパティであることを宣言します。外部公開されたプロパティには削除、名前の変更、圧縮、Compilerによるいかなる最適化も実施されなくなります。同じ名前のプロパティを個別に最適化することはできません。

ライブラリのコードに対しては @expose を使用すべきではありません。今まで正常に行われていたプロパティの削除を妨げることになるからです。
@extends
@extends 型名
@extends {型名}

例：
/**
 * 常に空のノードリスト
 * @constructor
 * @extends goog.ds.BasicNodeList
 */
goog.ds.EmptyNodeList = function() {
  ...
};
 @constructor と共に使用し、あるクラスが別のクラスを継承していることを示します。型を囲む波括弧は省略可能です。
@externs
@externs

例：
/**
 * @fileoverview これはexternファイルです。
 * @externs
 */

var document;
 externファイルであることを宣言します。
@fileoverview
@fileoverview 説明文

例：
/**
 * @fileoverview 何かをするユーティリティ群。その説明には
 * このように長くてインデントされていないコメントを必要とします。
 * @author kuth@google.com (Uthur Pendragon)
 */
 ファイルレベルの情報を提供するコメントブロックを構成します。
@implements
@implements 型名
@implements {型名}

例：
/**
 * 形状。
 * @interface
 */
function Shape() {};
Shape.prototype.draw = function() {};

/**
 * @constructor
 * @implements {Shape}
 */
function Square() {};
Square.prototype.draw = function() {
  ...
};
 @constructor と共に使用し、あるクラスがインタフェースを実装していることを示します。型を囲む波括弧は省略可能です。
@inheritDoc
@inheritDoc

例：
/**
 * @inheritDoc
 */
project.SubClass.prototype.toString() {
  // ...
};
 非推奨。 @override を使ってください。

サブクラスのメソッド・プロパティが、スーパークラスのメソッド・プロパティを意図的に隠蔽しており、全く同じJSDocコメントを持つことを示します。 @inheritDoc は @override を包含する点に注意してください。
@interface
@interface

例：
/**
 * 形状。
 * @interface
 */
function Shape() {};
Shape.prototype.draw = function() {};

/**
 * 多角形。
 * @interface
 * @extends {Shape}
 */
function Polygon() {};
Polygon.prototype.getSides = function() {};
 その関数がインタフェースであることを示すために使います。
@lends
@lends オブジェクト名
@lends {オブジェクト名}

例：
goog.object.extend(
    Button.prototype,
    /** @lends {Button.prototype} */ {
      isButton: function() { return true; }
    });
 オブジェクトリテラルのキーが他のオブジェクトのプロパティとして扱われるべきであることを示します。このアノテーションはオブジェクトリテラルにだけ付けられます。

他のアノテーションとは異なり、波括弧の中の名前はクラス名ではなくオブジェクト名である点に注意してください。それはプロパティが "lent"（貸与）されているオブジェクトの名前です。例えば @type {Foo} は "Fooのインスタンス" を意味しますが、 @lends {Foo} は "Fooのコンストラクタ関数" のことです。

このアノテーションについてのより詳しい説明はJSDoc Toolkit のドキュメント(日本語)を参照してください。
@license or @preserve
@license 説明文

例：
/**
 * @preserve Copyright 2009 SomeThirdParty.
 * このファイルに関する完全なライセンス条項と
 * 著作権表示を記載します。文章は複数行にわたっても構いませんが、
 * 必ず末尾は "*/" で閉じられている必要があります。
 */
 @license または @preserve が付けられたコメントはCompilerの処理から保護され、コンパイルされたコードよりも前に出力されます。コンパイルの影響を受けないことから、このアノテーションは重要な通知（ライセンスや著作権のような）を行うのに向いています。改行もそのまま残されます。
@noalias
@noalias

例：
/** @noalias */
function Range() {}
 Externファイルの中で使い、この変数または関数に別名を付けてはならないことをCompilerに示します。
@nosideeffects
@nosideeffects

例：
/** @nosideeffects */
function noSideEffectsFn1() {
  // ...
};
/** @nosideeffects */
var noSideEffectsFn2 = function() {
  // ...
};
/** @nosideeffects */
a.prototype.noSideEffectsFn3 = function() {
  // ...
};
 関数やコンストラクタに付けられ、それらの呼び出しが他のコードに影響を及ぼさないことを示します。このアノテーションはCompilerに対し、戻り値が使用されていない場合にそれらの関数を削除することを許可します。
@override
@override

例：
/**
 * @return {string} project.SubClassの人間が理解できる表現。
 * @override
 */
project.SubClass.prototype.toString() {
  // ...
};
 サブクラスのメソッド・プロパティが、スーパークラスのメソッド・プロパティを意図的に隠蔽していることを示します。コメントにこれ以外の記述が含まれない場合、スーパークラスで書かれた内容がサブクラスに引き継がれます。
@param
@param {型} 変数名 説明文

例：
/**
 * 各項目のBazを問い合わせます。
 * @param {number} groupNum 問い合わせのためのサブグループID。
 * @param {string|number|null} term 項目名、
 *     または項目ID、もしnullの場合は全て検索します。
 */
goog.Baz.prototype.query = function(groupNum, term) {
  // ...
};
 メソッド、関数、コンストラクタに対し、それらの引数を説明するために使用します。

型名は必ず波括弧で括られていなければなりません。型名が省略された場合、Compilerは型チェックを行いません。
@private
@private

例：
/**
 * このロガーを監視しているハンドラの配列。
 * @type Array.<Function>
 * @private
 */
this.handlers_ = [];
 メソッド・プロパティ名の末尾にアンダースコアを付加する仕様と組み合わせて、メンバがprivateであることを示します。
@protected
@protected

例：
/**
 * 指定されたDOM要素をコンポーネントのルート要素として設定します。
 * このメソッドのスコープはprotectedで、オーバーライドできません。
 * @param {Element} element コンポーネントのルート要素
 * @protected
 */
goog.ui.Component.prototype.setElementInternal = function(element) {
  // ...
};
 メソッド・プロパティがprotectedであることを示します。名前の末尾にアンダースコアを付けてはいけません。
@return
@return {型} 説明文

例：
/**
 * @return {string} 最後の項目の16進数表記のID
 */
goog.Baz.prototype.getLastId = function() {
  // ...
  return id;
};
 メソッドと関数に対し、それらの戻り値を説明するために使用します。論理型の戻り値の説明では、"コンポーネントが見えるならtrue、そうでなければfalse" よりも "コンポーネントが見えるかどうか" の方が良い書き方です。戻り値が無い場合、 @return タグは使わないで下さい。

型名は必ず波括弧で括られていなければなりません。型名が省略された場合、Compilerは型チェックを行いません。
@see
@see リンク

例：
/**
 * むやみに項目を追加します。
 * @see #addSafely
 * @see goog.Collect
 * @see goog.RecklessAdder#add
 ...
 他のクラス、関数、メソッドへの参照を記載します。
@struct
@struct 説明文

例：
/**
 * @constructor
 * @struct
 */
function Foo(x) {
  this.x = x;
}
var obj = new Foo(123);
var num = obj['x'];  // 警告
obj.y = "asdf";  // 警告

Foo.prototype = /** @struct */ {
  method1: function() {}
};
Foo.prototype.method2 = function() {};  // 警告
 コンストラクタ（左の例の Foo ）に @struct が付けられた場合、 Foo オブジェクトのプロパティへのアクセスはドットによる表記法でのみ可能となります。また、生成された Foo オブジェクトへ新しいプロパティを追加することはできません。アノテーションをオブジェクトリテラルに直接記述することもできます。
@supported
@supported 説明文

例：
/**
 * @fileoverview イベントマネージャ
 * ブラウザ固有のイベントシステムを抽象化した
 * インタフェースを提供します。
 * @supported これまで IE6 と FF1.5 でテスト済みです。
 */
 @fileoverview を含むコメントブロックで使用し、このファイルの内容をサポートするブラウザを記載します。
@suppress
@suppress {警告1|警告2}

例：
/**
 * @suppress {deprecated}
 */
function f() {
  deprecatedVersionOfF();
}
 ツールからの警告を抑止します。警告の種類が複数ある場合は | で区切ります。
@template
@template

例：
/**
 * @param {function(this:T, ...)} fn
 * @param {T} thisObj
 * @param {...*} var_args
 * @template T
 */
goog.bind = function(fn, thisObj, var_args) {
  ...
};
 このアノテーションはテンプレート型を宣言するために使用します。
@this
@this 型名
@this {型名}

例：
pinto.chat.RosterWidget.extern('getRosterElement',
/**
 * 名簿ウィジェットの要素を返します。
 * @this pinto.chat.RosterWidget
 * @return {Element}
 */
function() {
  return this.getWrappedComponent_().getElement();
});
 特定のメソッドが呼ばれるときのコンテキストの型を表します。thisがプロトタイプメソッドでない関数から参照されているときに必要です。
@type
@type 型名
@type {型名}

例：
/**
 * 16進数形式のID。
 * @type {string}
 */
var hexId = hexId;
 変数、プロパティ、式のデータ型を表します。ほとんどの型において波括弧で囲むことは必須ではありませんが、一貫性のためにそれを強制しているプロジェクトもあります。
@typedef
@typedef

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

/** @param {goog.NumberLike} x 数値か文字列 */
goog.readNumber = function(x) {
  ...
}
 このアノテーションは複雑な型に別名を付けるために使用します。

 

JavaScriptで使えるデータ型

型名の例 値の例 説明
number 1
1.0
-5
1e5
Math.PI
Number new Number(true) Numberオブジェクト
string 'Hello'
"World"
String(42) 		文字列値
String new String('Hello')
new String(42) 		Stringオブジェクト
boolean true
false
Boolean(0) 		論理値
Boolean new Boolean(true) Booleanオブジェクト
RegExp new RegExp('hello')
/world/g
Date new Date
new Date()
null null
undefined undefined
void function f() {
  return;
} 		戻り値なし
Array ['foo', 0.3, null]
[] 		型指定のない配列
Array.<number> [11, 22, 33] 数値の配列
Array.<Array.<string>> [['one', 'two', 'three'], ['foo', 'bar']] 文字列の配列の配列
Object {}
{foo: 'abc', bar: 123, baz: null}
Object.<string> {'foo': 'bar'} 文字列の値を持つオブジェクト
Object.<number, string> var obj = {};
obj[1] = 'bar'; 		キーが数値で値が文字列のオブジェクト。

JavaScriptではオブジェクトのキーは暗黙的に文字列に変換される点に注意してください。従って obj['1'] == obj[1] です。また for...in ループの中でもキーは常に文字列です。しかしCompilerはキーがオブジェクトの中でインデックスとして機能しているかどうかを識別します。
Function function(x, y) {
  return x * y;
} 		Functionオブジェクト
function(number, number): number function(x, y) {
  return x * y;
} 		関数
SomeClass /** @constructor */
function SomeClass() {}

new SomeClass();
SomeInterface /** @interface */
function SomeInterface() {}

SomeInterface.prototype.draw = function() {};
project.MyClass /** @constructor */
project.MyClass = function () {}

new project.MyClass()
project.MyEnum /** @enum {string} */
project.MyEnum = {
  /** 青色 */
  BLUE: '#0000dd',
  /** 赤色 */
  RED: '#dd0000'
}; 		列挙型

列挙値に対するJSDocコメントは省略可能です。
Element document.createElement('div') DOM要素
Node document.body.firstChild DOMノード
HTMLInputElement htmlDocument.getElementsByTagName('input')[0] DOM要素の型を明示的に指定します。