サイト開発の覚書ブログ

Webサービス(API)+JQuery(JS)を中心にPHP,CSS,HTMLでサイト開発する上で覚書となります。

JSDocでJavaScriptからドキュメントを自動生成する


目的

開発したソース(JavaScript)が動作するのは当然であり、

保守性の向上を目的にソース中のコメントから

JavaDoc風のドキュメントを自動生成する。


今回のゴールは環境構築~動作確認までとなり、コメントの書き方等は範囲外となる。

ダウンロードする

自動生成為に必要なモノは下記の4点となる。

(Antは④に同封されているが、本書では別途インストールする)


①Javaをダウンロードする
http://www.oracle.com/technetwork/java/javase/downloads/index.html


②Antをダウンロードする
http://www.apache.org/dist/ant/binaries/


③nodeをダウンロードする
https://nodejs.org/en/download/


④jsdoc3-ant-task-masterをダウンロードする
https://github.com/jannon/jsdoc3-ant-task


インストールする

①Javaをインストールする

ダウンロードしたjdk-8u91-windows-i586.exeをダブルクリックし次へ次へで完了。

(i586の32bit版である必要性は特にない。昔からの習慣です。)


②Antをインストールする

適当な場所に解凍するだけで完了。


③nodeをインストールする

ダウンロードしたnode-v6.0.0-x64.msiをダブルクリックし次へ次へで完了。


④jsdoc3-ant-task-masterをインストールする

適当な場所に解凍するだけで完了。


環境設定する

①Javaの環境を設定する

 設定手順

 1.Windowsのエクスプローラーを開き、コンピュータを右クリックする

 2.プロパティー→システムの詳細設定→詳細設定タブ→環境変数をクリックする

 3.ユーザの環境変数にJAVA_HOMEとJavaのインストール先を設定する


②Antの環境を設定する

 先の設定手順1と2を実行し、システムの環境変数:Pathの先頭にAntのインストール先を追加する。(セミコロンで区切る事)


③nodeの環境を設定する

 ナシ


④jsdoc3-ant-task-masterの環境を設定する

 1. Windowsのスタートボタンをクリックし、Node.js command promptを実行する。

 2. jsdoc3の追加モジュールの保存するDIRを適当な場所に作成する。

  注意)作成するDIRはjsdoc3-ant-task-masterディレクトリ配下に作成してはならない!

 3. 1のpromptで「cd jsdoc3の追加モジュールの保存DIR」を実行する。

 4. 1のpromptで「npm install git+https://github.com/jsdoc3/jsdoc.git」を実行する。

 5. 追加モジュールの保存DIRの下に.binディレクトリが追加されており、先の設定手順1と2を実行し、ステムの環境変数:Pathの先頭に追加する


実行する

 1. 新規にNode.js command promptを立ち上げる。

 2. promptで「cd jsdoc3-ant-task-masterをインストールDIR」に移動する。

 3. promptで「ant」を実行し、単体テストとドキュメントの自動生成を実行する。

 4. build\javadocs\index.htmlをブラウザで確認する。

 5. 独自のJavaScriptをsrcディレクトリに保存して、3を再実行し正しく出力されたか確認してみよう。