松山事務所の石丸です。
JavaScriptでは関数の引数や戻り値の型を書かないため、関数宣言だけでは伝えられない熱い想いをコメントで補う必要があります。
さらに業務ではドキュメントの作成も求められることが多いので、どうせならコメントからドキュメントが生成できるといいですよね。
Windows10(64bit)環境でJSDoc3を使ってドキュメントを生成してみます。

環境構築

Node.jsのインストール

まずはNode.jsをインストールします。
https://nodejs.org/ja/から 8.11.3 LTS をダウンロードしてインストールしました。

JSDoc3のインストール

次にnpmでJSDoc3をインストールします。コマンドプロンプトから以下のコマンドでグローバルにインストールしました。

ドキュメント生成

JSDoc形式でソースコードにコメントを記述したら、あとはコマンドプロンプトで以下のコマンドを実行するだけです。

カレントディレクトリに outフォルダ が作成され、その中にHTMLドキュメントが生成されているかと思います。

ドキュメントのテンプレートを変更する

出力されたドキュメントの構成やデザインを変えたい場合は、JSDocのテンプレートをインストールします。
今回は TUI JSDoc Templateを使ってみました。
デモページでどんな感じのドキュメントになるのか確認することができます。

テンプレートのインストール

TUI JSDoc Templateのインストールはnpmコマンドで行います。
カレントディレクトリに node_modules フォルダなどが生成されるため、作業フォルダを作成し、その中で実行しましょう。

JSDocの設定ファイル

このテンプレートを適用してドキュメント生成を行うため、以下のような内容の config.json ファイルを用意します。

この時点で作業フォルダ内は、以下のようになっているかと思います。

  • conf.jsonファイル
  • node_modulesフォルダ
  • package-lock.jsonファイル

ドキュメント生成

-c オプションで conf.json を指定し、ドキュメントを生成します。

きれいなドキュメントが outフォルダ に出力されたでしょうか？

まとめ

このようにドキュメントの生成自体は簡単なのですが、JSDoc形式でのコメントの記述が大変でした。
JavaScript(ES5.1)には型情報や継承を表すキーワードもないため、それらをすべてコメントで記述する必要があります。
またTypeScriptに学ぶJavaScriptの書き方のように即時関数を使用してのnamespaceの作り方と相性がよくないらしく、正しい構造のドキュメントを出力するのに苦労しました。
やっぱりTypeScriptで書きたいですね。

TOP
TOP