ESDocを使ってJSDoc形式のコメントからドキュメントを自動生成する

ESDocを使えばJSDoc形式で書いたコメントからドキュメントをhtml形式で自動生成できて大変便利である。以下に設定方法を記す。

esdoc と esdoc-standard-plugin を開発用にインストール

yarn を使った場合

yarn add -D esdoc esdoc-standard-plugin

設定ファイルの作成

package.json と同じディレクトリに「.esdoc.json」ファイルを以下の内容で作成。

.esdoc.json

{
    "source": "./src",
        "destination": "./docs",
        "plugins": [
    {
        "name": "esdoc-standard-plugin",
        "option": {
            "test": {
                "source": "./src"
            },
            "manual": {
                "files": [
                     "./manual/manual_1.md",
                     "./manual/manual_2.md",
                     "./manual/manual_3.md"
                 ]
            }
        }
    }]
}

「manual」で指定したmarkdownファイルをもとに一つのhtmlページが作られるのがとても便利。

同じディレクトリに「README.md」を作成

この「README.md」が作成されるドキュメントの index.html となるのでどうしても必要。ここにドキュメントの概要を書く。

package.json の script に実行コマンドを追加

package.json

"scripts": {
    "docs": "esdoc",
}

実行すると、jsファイル内のJSDoc形式のコメントからクラスやメソッドの詳細仕様書がhtmlで作成される。非常に便利である。