JSDocとは
JSDocコメントは形式が決まった特別なコメントです。
@typeや@paramなどのJSDocタグを使ってコメントを書けます。
JSDocコメントを書くと、VSCodeなどのエディタがコメントの内容を別の場所で表示してくれたり、ソースコードから自動でドキュメントを生成したりできます。
ドキュメントはこちらです。
用途
JSDocコメントは以下のような場所に書くのがおすすめです。
- 汎用的に使えるクラス / 関数に書く
- ライブラリを制作する場合、ユーザーから見えるもの対して書く
書き方
例えば、引数aとbを足して返す関数addを例に見てみます。
まずは実装を書きます。
function add(a, b) {
return a + b
}
実装はできましたが、呼び出し側はこれがどんな関数なのかわかりません。
おそらく以下の疑問が生まれることでしょう。
- 引数
aとbにはどのような型の値を入れるのか？ - 関数の戻り値は何なのか？
ここでJSDocの出番です。
JSDocコメントは対象となるもの（ここでは関数）の前の行に書きます。
また、/** */で囲む必要があります。
/** これがJSDocコメント */
function add(a, b) {
return a + b
}
囲んだ中には関数の説明を追加できます。
/** 引数の値を足して返す */
function add(a, b) {
return a + b
}
この説明は、例えばVSCodeのホバーしたときに出るツールチップに表示されます。
以下の画像では一番下のaddという行にホバーしています。
JSDocでは、JSDocタグと呼ばれる@から始まる文字列を使って、特定の形式で情報を書けます。
例えば関数の引数の説明には@paramを使います。
@paramは@param {引数の型} 引数名 説明という形式です。
/**
* 引数の値を足して返す
* @param {number} a 足す数1
* @param {number} b 足す数2
*/
function add(a, b) {
return a + b
}
ここではaとbの文字での説明と、これらはnumberであるという型の情報を追加しました。
型の情報はエディタのツールチップでも見れ、場合によっては戻り値の型を推論してくれることもあります。
主要なタグ
ここでは、個人的によく使うJSDocタグをまとめておきます。
一覧はドキュメントから見れるので、こちらも参考にしてみてください。
@param
関数 / メソッドの引数を説明するのに使えます。
- 構文:
@param {引数の型} 引数名 説明 - 引数の数だけ書ける
/**
* 引数の値を足して返す
* @param {number} a 足す数1
* @param {number} b 足す数2
*/
function add(a, b) {
return a + b
}
@returns
関数 / メソッドの戻り値を説明するのに使えます。
- 構文:
@returns {戻り値の型} 説明 - 基本的には一つの関数に一つまで
/**
* 引数の値を足して返す
* @returns {number} 足した数
*/
function add(a, b) {
return a + b
}
@type
変数の型や、クラスのフィールドの型を示すのに使えます。
- 構文:
@type {型} - その変数やフィールドの説明が先に来ることが多い
class Book {
/**
* 本のタイトル
* @type {string}
*/
title
}
@example
関数やクラスなどの使用例を示すのに使えます。
説明は、@exampleの次の行以降にサンプルコードを書く形となります。
また、Markdown形式で説明を書くこともできます。
/**
* 引数の値を足して返す
* @example
* add(1, 2) // 3
* add(5, 1) // 6
*/
function add(a, b) {
return a + b
}
VSCodeだと、ツールチップにこのように表示されます。
@deprecated
関数やクラスなどが非推奨であることを示すタグです。
- 構文:
@deprecated 説明 - 説明には代わりに何を使うべきか書いておくと親切かも
- 非推奨である関数やクラスのフィールドごとに一つまで
class Book {
/**
* 本の著者
* @type {string}
* @deprecated 代わりにauthorsを使うこと
*/
author
/**
* 本の著者の配列
* NOTE 著者は複数名いることもあるため、配列になっている
* @type {string[]}
*/
authors
}
VSCode上では、@deprecatedなものを使おうとすると、名前の上に取り消し線が引かれます。
