最近はJavaScriptを書くことが多く、「仕様書出せ！」と言われるのでJSDocでの記述・出力メモ。

やりたいこと

./srcフォルダに機能別に保存され、module.exportsされる関数の仕様を記述・出力する

セットアップ

めんどくさいのでグローバルにインストールします。

npm install -g jsdoc

サンプル

作業場所の準備

mkdir jsdoc-test
cd jsdoc-test
mkdir src
touch hello.js bye.js

hello.jsの記述

モジュールの場合は@moduleを付けてやらないと何も出力されない。

hello.js

/**
 * Helloという文字列を返します。
 * @module hello
 * @param {string} name - 表示したい名前を指定する。
 * @return {string} - [Hello + name]という形式で戻る。
 */
module.exports = hello = (name) => {
    return "Hello" + name;
}

bye.jsの記述

bye.js

/**
 * Helloという文字列を返します。
 * @module bye
 * @param {string} name - 表示したい名前を指定する。
 * @return {string} - [Bye + name]という形式で戻る。
 */
module.exports = bye = (name) => {
    return "Bye" + name;
}

Doc出力

jsdoc src

すると、同じ階層にoutというフォルダが作成される。その中のindex.htmlを見る。
下記のような内容が表示される（味気ない）。

右メニューのHelloを見ると下記のような感じ。

基本は以上。

応用１：Home画面に説明文を入れたい

Markdownで説明文を書いて、出力時に指定すれば取り込んでくれるみたい（便利）。

README.md

### テストAPIです。

以下の２つを作りました。

* hello()
* bye()

そして、

jsdoc src README.md

とすると、下記のようにHomeに出力されます。

応用２：Objectを記述する

JSではObjectを引数、戻り値に取ることもありますよね。。。下記のように記述するようです。

object.js

/**
 * Objectを受け取りObjectを返します。
 * @module object
 * @param {Object} user - ユーザーオブジェクト
 * @param {string} user.name - ユーザの名前。
 * @param {number} user.age - ユーザーの年齢。
 * @return {Object} result オブジェクトが戻る。
 * @return {string} result.status - "OK or NG"。
 * @return {string} result.message - メッセージが返ります。
 */
module.exports = object = (User) => {
    return { status: "OK", message: "hoge" }
}

が、returnはうまく表現できないのかな・・・。

応用３：テンプレートを変更する

しかしJSDocの標準テンプレートはなんでこんなに微妙なんだろ。。。せめて左メニューにしてくれたらいいのに。。。
変え方はひとまずリンクだけ。

こちらのサイトに紹介されているので一旦メモ。