JsDoc3-manual-jp - タグリファレンス

タグリファレンス

読み方

@author author_name

は

@author Foo Bar

のように書く。

@class [text]

のように[]で囲まれた部分は省略可能。

なお、typeは{string} や{MyClass.Foo}のような{}で囲まれた記述、name_pathはMyClass.Foo、MyClass-innerというように記述の目的が異なる。typeは型指定なのでインスタンス前置詞#や内部関数前置詞-を用いることができない。

詳しい仕様については、コードを直接読むとよくわかる。

タグは Closure Compiler の動作に影響を与えるものがある。それらのタグは下線付きにし。

@abstract, @virtual

@abstract

抽象クラスであることを示す。

開発者向けNote：

このタグのついたDocletオブジェクトはvirtualプロパティにtrueが設定される。

@access

@access [access_specifer]

アクセス修飾子を設定する。 access_specifer には public private protected が指定可能。それぞれ private タグ、 protected タグ、 public タグと記述されている場合と同じ動作。

暗黙に@access publicなので、publicは書かなくてもよい。

開発者向けNote:

このタグのついたDocletオブジェクトは、accessにundefined、'private'、'protected'のいずれかが設定される。

すべてのDocletは暗黙にpublicなので、access === undefined の場合はpublic とみなすことになっている。

@alias

@alias name_path

オブジェクトの別名を指定する。

@augments, @extends

@augments type|name_path

親オブジェクト（継承元）を示す。JsDoc2ではtypeを記述することができないので注意。

開発者向けNote:

このタグのついたDocletオブジェクトは、augmentsプロパティの配列に継承元のlongnameが入れられる。

このタグがない限り、augmentsプロパティは存在しないので配列を巡回処理する際には注意すること。

@author

@author author_name

このオブジェクトのソースコードのプログラマ情報を記載する。

Closure Compiler では、

@author foo@example.com (Your Name)

という書式が推奨されている。

@borrows

@borrows name_path [" as " name_path]

このオブジェクトの借用元のクラスを示す。

@constructor, @class

@class [text]

new 演算子が必要な関数であることを示す。 new 演算子が必要でない場合は function を使用するべき。

Closure Compiler は@classは処理できないので、使用しない方が無難。

代わりに@constructorを使うべき。

@classdesc

@classdesc text

クラスの説明文（≠コンストラクタの説明文）を示す。

@constant, @const

@constant type [text]

定数オブジェクトであることを示す。

開発者向けNote:

このタグのついたDocletオブジェクトのkindプロパティは 'constant' になる。

これは、定数関数の扱いを厄介にする。つまり、kind==='constant'で関数の場合には、

@param タグの有無等で関数かどうかを確認しなければ、引数や戻り値の出力ができない。

@constructs

@constructs [name_path]

特殊な記法でオブジェクト（クラス）を作成していることを示す。 makeClass や klass などの関数によってオブジェクトが作成される場合に設定する。（例）

@copyright

@copyright text

著作権情報を設定する。

@default, @defaultvalue

@default [value]

初期値を示す。 value には文字列・値・真偽値など設定可能。

開発者向けNote:

このタグのつけられたDocletは、defaultValueプロパティにvalueが設定される。

この際、valueが文字列と判定されると、文字列リテラルが外される。

@deprecated

@deprecated [text]

使用しないほうがよい旨を表示する。

@deprecated Use {@link foo.bar}

が一般的。

@description, @desc

@description text

オブジェクトの説明文を示す。タグが省略されている場合はこのタグだと見なされている。

このタグは使用しない方がよい。下のような記法の方がコードの見通しが良いからである。

/**

* タグをつかわずとも、この部分は@descriptionだとみなされるのだから、タグ使わなくていいよね。

@enum

@enum [type]

列挙型のオブジェクトであることを示す。メンバの型を指定できる。

例：

/**

* Description.

* @enum {string}

foo.Bar = {

/** Description. */

VAL1: 'val1',

/** Description.*/

VAL2: 'val2'

};

開発者向けNote 1:

このタグのつけられたDocletは、kindプロパティがmember、isEnumプロパティがtrueに設定される。

このプロパティの子要素には指定されたtypeが利用される。

開発者向けNote 2:

@enumのついたDocletのtypeプロパティにはメンバのタイプが設定されている。

これは、列挙型を納めたオブジェクトのtypeと一致しない。

したがって、@enumタグを見つけた場合には、そのDocletのtypeを'Object.<any type>'とするなどして正しいtypeに変換する必要がある。

@event

@event event_type

イベントを示す。

開発者向けNote:

このタグのつけられたDocletは、kindプロパティが'event'になる。

@example

@example text

コードの例を設定する。

@exception, @throws

@exception type

オブジェクトによって投げられる例外を設定する。

開発者向けNote:

このタグのつけられたDocletは、exceptionsプロパティに配列が設定され、要素にtypeが設定される。

@exports

@exports module_path

CommonJS Module 仕様のexportsとして外部に公開されるオブジェクトであることを示す。

@external

@external type|name_path

外部の名前空間（ライブラリ・モジュール）の参照を設定する。

開発者向けNote:

このタグのつけられたDocletは、kindプロパティが'external'に設定される。

@file, @fileoverview, @overview

@file text

ソースコードファイルについての説明を示す。

スクリプトの最上部（または、ライセンス表記の直下）に記述すると見通しが良くなる。

@fires

@fires name_path

発生するイベントを設定する。

@function, @func, @method

@function [name_path]

このオブジェクトが関数であることを示す。

通常は自動で判定してくれるので、うまく判定されない場合にのみ記述すればよい。

@global

このオブジェクトがグローバルオブジェクトであることを示す。

開発者向けNote:

このタグのつけられたDocletのscopeプロパティが'global'に設定される。

memberofプロパティは削除される。

@ignore

最終的な出力には含まれないオブジェクトであることを示す。

たぶん Closure Compiler などの圧縮・最適化ツールによる削除・リネームによって使用できなくなることを示すために使われる。

@inner

オブジェクトが内部関数であると示す。

通常は自動で判定してくれるので、うまく判定されない場合にのみ記述すればよい。

@instance

オブジェクトがインスタンスであると示す。

@kind

@kind kind

オブジェクトの種類を示す。

kindの振る舞いは非常に特殊なので、使用を避けるべき。

開発者向けNote:

kindプロパティが設定される。

@lends

@lends name_path

直後の無名関数・オブジェクトのメンバが、name_pathで指定されたクラスのメンバであることを示す。

（例 lendsて内部検索してね）

@license

@license text

ライセンス情報を示す。

@member, @var

@member [type] [text]

オブジェクトがメンバであると示す。

通常は自動で判定してくれるので、うまく判定されないる場合にのみ記述すればよい。

@memberof, @memberof!

@memberof name_path

このオブジェクトの属しているオブジェクトを設定する。

通常は自動で判定してくれるので、うまく判定されない場合にのみ記述すればよい。

@mixes

@mixes name_path

このオブジェクトのメンバがすべて他のオブジェクトのメンバであることを示す。

@mixin

mix-in継承されたオブジェクトとして示す。

@module

@module module_path

このファイルがCommonJSなどのモジュールを構成することを示す。モジュールパスは / 記号区切りで記述する。

スクリプトの最上部（または、ライセンス表記の直下）に記述すると見通しが良くなる。

例：

/** @module Foo */

@name

@name name_path

オブジェクトの名称を設定する。オブジェクトの名称は通常はJsDocが構文から判断しているが、特殊な構文でうまく名前が設定されない場合に使用する。

@namespace

@namespace [type]

このオブジェクトが名前空間オブジェクトであることを示す。

@param, @arguments, @arg

@param [type] [name] [text]

この関数の引数を設定する。

@private

このオブジェクトがプライベートメンバであることを示す。

@property, @prop

@property [type] [name] [text]

このオブジェクトがプロパティであることを示す。

@protected

このオブジェクトがプロテクテッドメンバであることを示す。

@public

このオブジェクトがパブリックメンバであることを示す。 private タグ、 protected タグ、 inner タグ、 access タグが設定されていない場合は自動的にパブリックメンバとなっている。

@readonly

読込専用のオブジェクトであることを示す。

@requires

@requires module_path

必要なライブラリやモジュールなどを設定する。

@returns, @return

@returns [type] [text]

戻り値を設定する。通常はコンストラクタには記述しないのが普通。

@see

@see name_path|uri

他に参照するべきオブジェクトかURIがあるときに設定する。ドキュメントにはそのオブジェクトまたはURIのリンクとして出力される。

@see {@link example.com} はバグる可能性があるので避けるべき。URIは@see example.comのようにベタで書きましょう。

@since

@since version

このオブジェクトが有効になったバージョンを設定する。 version は . 区切りの数字。

@static

このメンバが静的メンバであることを示す。

通常は自動で判定してくれるので、うまく判定されない場合にのみ記述すればよい。

@summary

@summary text

説明の要約を設定する。

@this

@this name_path

this キーワードが示すオブジェクトを設定する。

このタグは、インスタンス外の静的な関数等で this を参照している場合につけるべき。

そうすると、Closure Compiler がきちんと面倒を見てくれるようになる。

@todo

@todo text

このオブジェクトについてToDo（やるべき事柄）を設定する。

@tutorial

@tutorial text

チュートリアルを設定する。 exmple タグとの違いはいまいちわからない。

@type

@type type|name_path

オブジェクトの型を設定する。

通常は、プロパティの詳細な型情報を記述する際に使う。

@typedef

@typedef [type] [name] [text]

複雑なオブジェクトの型の別名を定義する。

こんなふうにつかう。

/**
* @typedef {Array|NodeList|Arguments|{length: number}}
*/ goog.array.ArrayLike;

/**
* Returns the last element in an array without removing it.
* @param {goog.array.ArrayLike} array The array.
* @return {*} Last item in array.
*/
goog.array.peek = function(array) { return array[array.length - 1]; };

@undocumented

このタグのつけられたオブジェクトのコメントは無視される（だったら書くな）。

@variation

@variation variation_number

同名のオブジェクトがある場合の識別番号を指定する。 variation_number は整数。

@version

@version version

バージョン情報を設定する。 version は . 区切りの数字。