JsDoc Toolkitを使う!
ドックコメントの書き方
最終更新:
aias-jsdoctoolkit
トップページ >
ドックコメントの書き方
このページ以下では、ドックコメントの書き方について説明します。
- 各タグの詳細なリファレンスはこちらを参照してください。
基本的な書き方
JsDoc Toolkitのドックコメントの書き方はJavaDocの記法をベースにしています。基本的な記述ルールは以下のとおりです。
- ドックコメントは /** から始まり */ で終わるコメントブロックで、複数行に渡って書くことができます。ドックコメントはタグと説明文から構成されます。
- 一般的にドックコメントは、その直後に現れるソースコードを対象にする記述と解釈されます。(ただし、@nameタグなど例外もあります)
- タグは"@"から始まるキーワードで、ドックコメントの対象に対し様々な意味づけを行います。タグは説明文を伴うこともあります。
- タグは行の先頭に書かれている必要があります。@linkタグを除き、行の途中に書かれたものはタグと解釈されませんので注意してください。
-
説明文はHTMLテキストで、HTMLタグを使用できます。複数行に渡って記述することができますが、改行は認識されません。
出力されたドキュメントの中で改行を行いたい場合は<br>タグを使ってください。 - ドックコメントの先頭に書かれた説明文は、そのドックコメントが対象とするコード内の要素そのものの説明と解釈されます。詳細は@descriptionタグの解説を参照してください。
- 慣習的に各行の行頭に * が書かれることがありますが、パース時にはこの部分は無視されます。 * の有無が処理結果に影響を与えることはありません。
ドックコメントの例
function incrementNumber(num) {
return num + 1;
}
上は関数へのドックコメントの例です。最初の行にタグなしで書かれた説明文は、関数そのものの説明です。(@descriptionタグで記述した説明文と等価です)
@paramタグは引数の説明で、引数が複数ある場合は引数分列挙します。@returnsタグは戻り値の説明です。引数、戻り値が無い場合、これらを記述する必要はありません。
関数がクラスコンストラクタの場合、以下のように記述します。この記述はクラス定義とコンストラクタ関数の説明を兼ねています。
最初の行の説明文は、(クラスではなく)コンストラクタの説明です。クラス全体の説明は@classタグに記述します。@classタグがあることでこの関数はJsDoc Toolkitにコンストラクタとして認識されるため、ここでは@constructorタグは必要ありません。
/**
* 新しいPersonオブジェクトを作成する。
*
@class
一人の人間をあらわすクラス
*
@param
{String} name 名前
*
@param
{Number} sex 性別。0=男、1=女
*/
function Person(name, sex) {
/**
* 名前
*
@type
String
*/
this.name = name;
/**
* 性別。0=男、1=女
*
@type
Number
*/
this.sex = sex;
}
関数内のドックコメントは、プロパティ(メンバ変数)に対するものです。例によって先頭行のタグなし説明文はプロパティの説明で、@typeタグはプロパティのデータ型を示します。プロパティへのドックコメントは、@propertyタグを使うともっと簡潔に書けます。
/**
* 新しいPersonオブジェクトを作成する。
*
@class
一人の人間をあらわすクラス
*
@param
{String} name 名前
*
@param
{Number} sex 性別。0=男、1=女
*
@property
{String} name 名前
*
@property
{Number} sex 性別。0=男、1=女
*/
function Person(name, sex) {
this.name = name;
this.sex = sex;
}
メソッドへのドックコメントの書き方は関数とほぼ同じです。通常メソッドとそれが属するクラスの関係はソースコードからJsDoc Toolkitが自動的に判定しますが、下の例のようにメソッドとクラスの関係が直接的でない場合は、@memberOfタグにネームパスを指定し、関係を明示する必要があります。
Person.prototype.walk = walk;
/**
* 歩く。
*
@memberOf
Person#
*/
function walk() {
//.....
}
@memberOfタグの記述で Person の後ろに"#"が付いた場合、関数はインスタンスメソッドとして出力されます。"#"が無い場合、関数はスタティックメソッドとして出力されます。
複雑な記述法への適用
prototype.jsなどのJavaScriptライブラリで使用されている記述法に対してドックコメントを適用する方法については、公式サイトのこちらのページを参照してください。
その他の記法など
名前が"_"から始まるメンバ
名前が"_"から始まるメンバは、JsDoc Toolkitによってprivateなスコープのメンバとして処理されます。privateなメンバは -p コマンドラインオプションを指定しない限りドキュメントに出力されません。
インライン・ドックコメント
インライン・ドックコメントはパラメータのデータ型をコード内に記述するドックコメントの書き方です。詳細はこちらを参照してください。
メタタグ
メタタグはJsDoc Toolkitに対する命令をあらわす特殊なドックコメントです。詳細はこちらを参照してください。
/**
* 数値に1を加算して返す。
* @param {Number} num 数値
* @returns {Number} 引数で与えられた数値に1を加算した数値
*/