JSDoc / JSのドキュメント生成ツール


JSDoc」はJavaScriptのAPIドキュメントを生成するツールです。JSDocでコメントを記述することで、JetBrainsやVisual StudioなどのIDEでコード保管やヒントを出すことができます。

🎂 インストール手順

JSDocはnpmからインストールできます。

npm install jsdoc --save

JSDocでドキュメントを生成するのは次のコマンドです。

./node_modules/.bin/jsdoc yourJavaScriptFile.js

😀 文法チートシート

@param : 関数の引数

/**
* 関数の説明
* @param {string} str - 文字列の引数
* @param {number} num - 数値の引数
* @param {Object} obj - オブジェクトの引数
* @param {MyClass} myClass - MyClassインスタンスの引数
*/
function doSomething(str, num, obj, myClass) {}

引数をオプショナル(与えなくてもよい)や、デフォルト値を指定できます。

/**
* 関数の説明
* @param {string} [str] - 文字列の引数 (オプショナル)
* @param {number} [num=300] - 数値の引数 ()オプショナルでデフォルト値は3000
*/
function doSomething() {}

@return : 返り値

/**
* 関数の説明
* @return {boolean} 真偽値を返す
*/
function doSomething() {}

@throw : 関数の返す例外

/**
* 関数の説明
* @trhow {string} エラーメッセージを例外として出力
*/
function doSomething() {}

@constructor : コンストラクタ関数の宣言

/**
* コンストラクタの説明
* @constructor
*/
function myClass() {}

@classdesc : クラスの説明

/**
* @classdesc クラスの説明
*/
function myClass() {}

@example : 実装例を提示

/**
* @example
* console.log(plus(1, 3)); => 4
*/
function plus(a, b) {
return a + b;
}

@deprecated : 非推奨の宣言

/**
* @deprecated 非推奨の理由。代替メソッドの提示
*/
function doSomething() {}

🐠 参考リンク

📚 おすすめの書籍