documentationjsはJSDocからドキュメントを生成できるツールで、ES2015以降のコードにも対応しています。 (TypeScriptは対応してないようです)

以前はMarkdownへの出力が難しかったのですが、いつのまにかdocumentation build -f mdでMarkdownでのAPIドキュメントが生成できるようになっていました。

これを使うことで、ライブラリを書いてそのJSDocからドキュメントを生成して、READMEのUsageセキュクションを自動的に更新できるようになっています。

以前もできたのですが、かなりトリッキーなテーマを書いたりしないといけませんでした。(後stdoutへの出力がなかった気がします)

やり方

必要なものはdocumentationjsとadd-text-to-markdownです。 add-text-to-markdownは標準入力の内容をMarkdownの特定のセクションに上書きするシンプルなCLIです。

サンプルリポジトリ

インストール

npm install --save-dev documentation add-text-to-markdown

JSDoc付きのコードを書く

documentationjsはあくまでJSDocからドキュメントを作るツールなので、JSDoc を書いたコードが必要です。

今回はsrc/index.jsというコードを例にします。

/**
 * Return Hello message
 * @param {string} name
 * @returns {string}
 * @example
 * hello("john"); // => "Hello, john"
 */
function hello(name) {
    return `Hello, ${name}`;
}

/**
 * update property with `propertyValue` if the `propertyName` does not exists
 * @param {*} object
 * @param {string} propertyName
 * @param {string} propertyValue
 * @param { {force: boolean} } options
 * @example
 * const object = {};
 * update(object, "key", "value", { force: true })
 * console.log(object); // { key: "value" }
 */
const updateProp = (object, propertyName, propertyValue, options = { force: false }) => {
    if (object[propertyName] && options.force) {
        object[propertyName] = propertyValue;
    } else if (object[propertyName]) {
        // no update
    } else {
        object[propertyName] = propertyValue;
    }
};

/**
 * @class
 */
class Myclass {
    /**
     * report message
     * @param {string} message
     */
    report(message) {

    }
}

export {
    hello,
    updateProp
}

JSDoc を MarkdownにしてRAEDMEに追加する

このコードは次のようにしてJSDocからMarkdownへ変換できます。

documentation build -f md src/index.js

この出力内容を使ってREADMEの”Usage”セクション(HeaderがUsageのところ”をadd-text-to-markdownで更新します。

add-text-to-markdownは標準入力を受け取るので、そのままパイプ処理で更新できます。

documentation build -f md src/index.js | add-text-to-markdown README.md --section "Usage" --write

結果

次のような感じでREADMEの”Usage”がJSDocのAPIドキュメントになりました。

おわり

この方法はライブラリを書いてREADMEに使い方を書くようなスタイルだとかなり自動化ができて便利です。documentationjsはJavaScript(JSDoc)しか対応してないので、使える範囲が限られますが、TypeScriptとかも同じようなことができるといいなーと思いました。

具体例