JSDocを利用することでドキュメントを出力したり、入力補完をサポートすることができます。ここでは、そんなJSDocの書き方をサンプルと共に紹介します。
JSDocの書き方
JSDocは複数行コメントの/**と*/で囲まれた範囲内で特定のタグを記述する必要があります。例えば以下のようなコードです。
/**
* 足し算する
* @param {number} a 足される数
* @param {number} b 足す数
* @returns
*/
const calc = (a, b) => {
// 数値型としての入力補完が効く
return a + b;
}
console.log(calc(10, 20)); // 30コメント1行目の文章はcalc変数の説明文になります。calc変数をホバーすることで、「足し算する」という説明文が表示されます。
2,3行目のタグはcalcの引数aとbがそれぞれ数値型であると宣言しています。このように明示的に宣言することで、calc内で入力補完を効かせることができるようになります。
3行目のタグはcalcの返り値を表しています。今回は数値型の足し算ということで暗黙的に数値型が返されていますが、@paramタグと同様に波括弧で囲むことで明示的に型を宣言することもできます。
代表的なタグ
JSDocはさまざまなタグをサポートしていますが、ここではよく利用するタグを紹介します。
@type
このタグを利用することで型を参照することができます。
const image = document.querySelector("img"); // image: HTMLImageElement
image.alt = "入力補完が効く";
const image2 = document.querySelector(".img"); // image2: Element
image2.alt = "入力補完が効かない";
/**
* @type {HTMLImageElement}
*/
const image3 = document.querySelector(".img"); // image3: HTMLImageElement
image3.alt = "入力補完が効く"1行目のimage変数はquerySelectorメソッドの引数にimgタグを指定しているため、変数の型はHTMLImageElementとなっています。そのため、altプロパティなどの入力補完が効いています。
対してimage2変数は引数にクラスを指定しています。クラス指定ではそれがどのタグなのか判断できないため、変数の型はElementとなってしまいます。Element型ではaltプロパティの入力補完を効かせることができません。
このような状況で@typeタグが活躍します。image3変数でも引数にクラスを指定していますが、タグを利用して変数の型はHTMLImageElementであると明示的に宣言しています。そのためimage3変数はHTMLImageElement型であると判断され、altプロパティなどの入力補完が効くようになります。
@param
このタグを利用することで引数の名前、型、説明を宣言することができます。同義語として@argや@argumentがあります。
/**
* @param {string | number} a
* @param {string} [b="b"] デフォルト引数
*/
const paramSample = (a, b = "b") => {
if (typeof a === "string") {
// a: string
console.log(a.length);
} else if (typeof a === "number") {
// a: number
console.log(a.toString());
}
console.log(b)
}引数の名前を角括弧で囲むことでその引数をオプションとして宣言することができます。
@typedef
@typedefタグを利用することで複雑な型を定義することができます。@typeタグや@paramタグなどと組み合わせて利用されることが多いです。
/**
* @typedef {Object} User
* @property {number} id
* @property {string} name
*/
/**
* 入力補完が効く
* @type {User[]}
*/
const users = [
{
id: 1,
name: "user1"
},
{
id: 2,
name: "user2"
},
];
/**
* @param {User} user
*/
const typedefSample = (user) => {
console.log(user.id); // 入力補完が効く
}ドキュメント生成
ここでは今回のサンプルコードを、jsdocパッケージを利用してドキュメント生成を行います。
$ npm i -D jsdoc
$ ./node_modules/.bin/jsdoc script.js -d docsまずnpmコマンドでjsdocパッケージのインストールをします。
その後、jsdocコマンドを実行し、script.jsファイルのドキュメントを作成しています。なお、-dは出力先フォルダを指定できるオプションです。今回の場合はdocsフォルダ内に出力しています。その他のオプションについては-hオプションで確認することができます。
docsフォルダを確認してみると、ドキュメントがHTMLファイルとして出力されていると思います。
