jsdoc3によるJavascriptドキュメント作成

はじめに

以前、YUIDocに関するJavaScriptのドキュメント作成方法について、このブログで紹介しました。

どうも、調べているとjsdocのほうが一般的？（何をデファクトスタンダードとするかは基準に迷うところです）のようなので、改めてjsdocの生成について行ってみようと思います。

Goals

さて今回の目標設定は以下としました。

1. Eclipse上でドキュメント生成する。
2. Eclipse上でコメント記入中にリアルタイムにプレビューしたい。（これは難しそう）
3. JavaScriptのコーディング中に生成したドキュメント参照できるようにする。

実施環境

• Eclipse  Mars Release (4.5.0)
• java version "1.8.0_51"

１．Eclipse上でドキュメント生成

まずこの目標ですが、今回はMavenを利用してpom.xmからJavaScriptのドキュメントを自動生成するようにしてみようと思います。

プロジェクト構成

  HellowWorld
    │

    │   pom.xml

    └─src

          │
          └─main

                │
                └─webapp

                      │
                      └─js

                            │
                            └─jsdoc3sample.js

pom.xmlの定義

pom.xmlの構成のポイント

• outputDirectory：
  言わずと知れた。ドキュメントを出力する場所です。今回はMavenのビルドパス上に作成するようにしてみました。
• jsdocInput：
  ドキュメント作成するJavaScriptを指定します。

サンプルJavaScriptファイル

まだ、ドキュメント用のコメント記述が良く分かっていないところもありますが、とりあえず以下のサンプルを作成しました。

ビルド実施

Eclipseでプロジェクトを選択して、以下のコマンドを実行です。

コマンド

> mvn clean jsdoc3:jsdoc3

Eclipse上から実行する場合

EclipseのメインメニューからRun(R)-Configuretionsを選択するとRun Configurationsダイアログが表示されます。

左側のツリーにてMaven Build下に新しいビルドを追加

Name:ご自由に

Base directory:対象のプロジェクトを選択

Goals：jsdoc3:jsdoc3

上記の内容を入力し、Runをクリック

ドキュメントが生成が成功すると上記の内容がコンソールに表示されます。

成功するとProject Explorerのtargetフォルダを再描画（F5キーを押す）するとjsdoc3フォルダが表示されます。

jsdoc3フォルダ配下のindex.htmlをブラウザで開くとドキュメントが作成されていることが分かります。

以上で、ドキュメント作成までの流れは終了です。

２．Eclipse上でコメント記入中にリアルタイムにプレビューしてみる。

Javaだと以下の画面のように、作成中のドキュメントを簡易ではあるが確認できる。

こんな感じで、作成しながら確認できればうれしい！！

とりあえずEclipseのViewをあさってみると以下のようなものがったので使ってみる。

EclipseのメインメニューからWindow(W)-Show View-Other...を選択するとShow Viewダイアログが表示されます。

JavaScript - Documentationを選択してOKをクリックする。

Documentationビューの動作を確認してみる

表示される。

表示されない。

これだけでは表示されないケースがあるみたいです。これはJsDocの記述が悪いのか、そもそもJsDocにツールが対応していないのか．．．

引き続き調査して、何か見つかったら追って更新します。

３．作成したドキュメントとの紐付け方

探してみましたが、そもそも、EclipseからJavaScriptのHelpを呼び出すという仕組みは見当たりませんでした。

正直これが出来ないと、つくったドキュメントを一番活用するのはコーディング中です。つまり統合開発環境と連携できないとドキュメントを見てもらえるケースが激減するので、作成に気合が入らなくなってしまいます。

総評

以下の3つの目標を立てましたが、残念ながら今回はコンプリートできませんでした。

解決策が見えましたら、随時更新していきます。

1. Eclipse上でドキュメント生成する。
   
   ⇒ mavenにて自動的に作成できるので、クリア
2. Eclipse上でコメント記入中にリアルタイムにプレビューしたい。（これは難しそう）
   
   ⇒ コメントの記述方法が悪いのかjsdocが対応していないのかコツを掴むのに時間がかかりそう、とりあえず継続利用して何か分かりましたらページを更新しいます。
3. JavaScriptのコーディング中に生成したドキュメント参照できるようにする。
   
   ⇒ 全く、見つけれませんでした。すみません。