はじめに
以前、YUIDocに関するJavaScriptのドキュメント作成方法について、このブログで紹介しました。
どうも、調べているとjsdocのほうが一般的？（何をデファクトスタンダードとするかは基準に迷うところです）のようなので、改めてjsdocの生成について行ってみようと思います。
Goals
さて今回の目標設定は以下としました。
- Eclipse上でドキュメント生成する。
- Eclipse上でコメント記入中にリアルタイムにプレビューしたい。（これは難しそう）
- JavaScriptのコーディング中に生成したドキュメント参照できるようにする。
実施環境
- Eclipse Mars Release (4.5.0)
- java version "1.8.0_51"
１．Eclipse上でドキュメント生成
まずこの目標ですが、今回はMavenを利用してpom.xmからJavaScriptのドキュメントを自動生成するようにしてみようと思います。
プロジェクト構成
HellowWorld
│
│
│ pom.xml
└─src
│
└─main
└─main
│
└─webapp
└─webapp
│
└─js
└─js
│
└─jsdoc3sample.js
└─jsdoc3sample.js
pom.xmlの定義
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| <plugin> | |
| <groupId>fr.mastah.maven.plugin</groupId> | |
| <artifactId>jsdoc3-maven-plugin</artifactId> | |
| <version>1.0.11</version> | |
| <executions> | |
| <execution> | |
| <id>jsdoc3</id> | |
| <phase>process-classes</phase> | |
| <goals> | |
| <goal>jsdoc3</goal> | |
| </goals> | |
| </execution> | |
| </executions> | |
| <configuration> | |
| <outputDirectory>${project.build.directory}/jsdoc3</outputDirectory> | |
| <jsdocInputs> | |
| <jsdocInput> | |
| <jsDir>${basedir}/src/main/webapp/js</jsDir> | |
| <pattern>.*.js</pattern> | |
| </jsdocInput> | |
| </jsdocInputs> | |
| <jsdocExclusions> | |
| <jsdocExclusion>intro.js</jsdocExclusion> | |
| <jsdocExclusion>outro.js</jsdocExclusion> | |
| </jsdocExclusions> | |
| <options>-p</options> | |
| </configuration> | |
| </plugin> |
pom.xmlの構成のポイント
- outputDirectory：
言わずと知れた。ドキュメントを出力する場所です。今回はMavenのビルドパス上に作成するようにしてみました。 - jsdocInput：
ドキュメント作成するJavaScriptを指定します。
サンプルJavaScriptファイル
まだ、ドキュメント用のコメント記述が良く分かっていないところもありますが、とりあえず以下のサンプルを作成しました。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| /** | |
| * <p>ログ出力クラス</p> | |
| * ブラウザのコンソールにログを出力します。<br /> | |
| * 使い方（通常）<br /> | |
| * <pre> | |
| * Logger.info('出力メッセージ'); | |
| * </pre> | |
| * <br/> | |
| * ストップウォッチ<br /> | |
| * <pre> | |
| * Logger.stopWatch.start(); | |
| * Logger.stopWatch.lap('ラップメッセージ'); | |
| * Logger.stopWatch.stop('完了メッセージ'); | |
| * </pre> | |
| * <br/> | |
| * | |
| * @namespace | |
| * @property {number} logLevel - ログ出力レベル | |
| */ | |
| Logger = { | |
| ALL:0, TRACE:1, DEBUG:2, INFO:3, WARN:4, ERROR:5, FATAL:6, OFF:9, | |
| logLevel: 2, | |
| className: '', | |
| methodName: '', | |
| /** | |
| * タイム測定 | |
| * @namespace | |
| */ | |
| stopWatch : { | |
| _startTimer : undefined, | |
| _lapTime : undefined, | |
| /** | |
| * ストップウォッチ（START） | |
| * @function | |
| */ | |
| start : function() { | |
| Logger.stopWatch._startTimer = new Date(); | |
| }, | |
| /** | |
| * ストップウォッチ（LAP） | |
| * @function | |
| */ | |
| lap : function(message) { | |
| var currentTime = new Date(); | |
| var totalTime = currentTime - Logger.stopWatch._startTimer; | |
| var laptime = '初回測定'; | |
| if (Logger.stopWatch._lapTime != undefined) { | |
| laptime = currentTime - Logger.stopWatch._lapTime; | |
| } | |
| console.log(message + ' 全体経過時間 - ' + totalTime + 'ms経過 前回との差分 - ' | |
| + laptime + 'ms'); | |
| Logger.stopWatch._lapTime = currentTime; | |
| }, | |
| /** | |
| * ストップウォッチ（STOP） | |
| * @function | |
| */ | |
| stop : function(message) { | |
| var currentTime = new Date(); | |
| console.log(message + ' 経過時間 - ' | |
| + (currentTime - Logger.stopWatch._startTimer) + 'ms経過'); | |
| } | |
| }, | |
| trace: function() { | |
| if (Logger.logLevel <= Logger.TRACE) { | |
| console.log(Logger._getMessage('TRACE', arguments)); | |
| } | |
| }, | |
| debug: function() { | |
| if (Logger.logLevel <= Logger.DEBUG) { | |
| console.log(Logger._getMessage('DEBUG', arguments)); | |
| } | |
| }, | |
| info: function() { | |
| if (Logger.logLevel <= Logger.INFO) { | |
| console.log(Logger._getMessage('INFO', arguments)); | |
| } | |
| }, | |
| warn: function() { | |
| if (Logger.logLevel <= Logger.WARN) { | |
| console.log(Logger._getMessage('WARN', arguments)); | |
| } | |
| }, | |
| error: function() { | |
| if (Logger.logLevel <= Logger.ERROR) { | |
| console.log(Logger._getMessage('ERROR', arguments)); | |
| } | |
| }, | |
| fatal: function() { | |
| if (Logger.logLevel <= Logger.FATAL) { | |
| console.log(Logger._getMessage('FATAL', arguments)); | |
| } | |
| }, | |
| /** | |
| * ログに出力するためのメッセージを構築するローカルメソッド | |
| * @private | |
| * @function | |
| * @param arguments 置換文字列 | |
| */ | |
| _getMessage: function(level, arguments) { | |
| var message = dateFormat(new Date()) + ' ' + level + ' '; | |
| if (this.className) { | |
| message = message + '[' + this.className + '] '; | |
| } | |
| if (this.methodName) { | |
| message = message + '(' + this.methodName + ') '; | |
| } | |
| switch (arguments.length) { | |
| case 0: | |
| message= message + 'no message!!'; | |
| break; | |
| case 1: | |
| message= message + arguments[0]; | |
| default: | |
| // @TODO これから作成（） | |
| } | |
| return message; | |
| }, | |
| /** | |
| * スタックとレース情報の出力 | |
| * @function | |
| * @param e | |
| */ | |
| printStackTrace: function(e) { | |
| if (e.stack) { | |
| console.log(e.stack); | |
| } else { | |
| console.log(e.message, e); | |
| } | |
| } | |
| }; |
ビルド実施
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つの目標を立てましたが、残念ながら今回はコンプリートできませんでした。
解決策が見えましたら、随時更新していきます。
- Eclipse上でドキュメント生成する。
⇒ mavenにて自動的に作成できるので、クリア - Eclipse上でコメント記入中にリアルタイムにプレビューしたい。（これは難しそう）
⇒ コメントの記述方法が悪いのかjsdocが対応していないのかコツを掴むのに時間がかかりそう、とりあえず継続利用して何か分かりましたらページを更新しいます。 - JavaScriptのコーディング中に生成したドキュメント参照できるようにする。
⇒ 全く、見つけれませんでした。すみません。
0 件のコメント:
コメントを投稿