Web開発プロジェクトでのJavadocの運用方法について現時点(2015年11月)でどのように利用すべきか検討したのでまとめてみました。
実際は使用できるツールやサーバが限られるし、現状によってはいきなりJavadocを使用できないかもしれないので以下のすべてを設定できるかというと難しいのですが。
あくまで私見なのでもっといいツールや運用方法があればコメントください。
前提
- JavaによるWeb開発
- 構成管理ツールとしてchefを使用
- インテグレーションツールとしてJenkinsを使用
- プロジェクト管理ツールとしてredmineを使用
- 単体テストではJUnitを使用
- 内部結合テスト以降、テストではselenium, appiumを使用
- 開発者のIDEとしてEclipseを使用
目的
- 開発効率の向上
- 納品ドキュメント作成工数の削減
- 属人化の排除
- 開発者のスキルアップの促進
- 開発者の手抜き・抜け漏れの防止
構成管理者の設定
出力文字コードの指定
ソースコードの文字コードと合わせる事。良く忘れて文字化けするので。当然ant.xmlに設定しておいて開発者が意識せずに使えるようにしておく事。
Javadocのオプションに以下を追加する。
-encoding utf-8
-charset utf-8
Javadocタイトル設定
Javadocを表示するブラウザのタイトルバーに表示されるタイトルを設定
Javadocのオプションに以下を追加する。
-windowtitle HogeHogeプロジェクト
Javadocの先頭ページ(概要ページ)の設定
Javadocの先頭ページ（概要ページ）にアプリケーションの説明、環境、バージョン情報等を持たせる。selenium等のテストの場合はテスト前提条件、観点等も記載する事。
参照：Javadocの概要ページ設定
クラスパスmain以下のクラス図出力設定
main以下のJavadocにはクラス図を自動で出力しておくと何気に見直した時に使い方の間違いに気づく時がよくある。デザインパターンを確認する場合にも役立つ。何より開発者がクラス図とコーディングの関係を学習するのでスキルアップにつながる。
参考：Eclipse+APIvizでjavadocにクラス図を出力
開発者が実施する事
Javadocパッケージ概要説明
Javadocのパッケージ先頭ページにパッケージの概要説明を持たせる。当然、main以下はそのパッケージの説明、test以下は何のパッケージの単体テストかの説明、selenium等のテストの場合はシナリオ別にパッケージを分けてシナリオの説明、前提条件、テスト観点を記載する。
参照：Javadocの概要ページ設定
Javadocクラス／メソッド説明
クラス説明は必須。packageメソッド以上のメソッド(他クラスから参照が可能なメソッド)は必須。privateメソッドは任意。
クラスは一行コメント、作成者(＠auther:生成したhtmlには表示しない)は必須。
メソッドは一行コメント、パラメータ(＠param)、戻値(＠return)、スロー(＠throw)は必須selenium, appiumのシナリオ説明
シナリオ、ケース毎にJavadocで説明を作成する。シナリオ番号、ケース番号はクラス名、メソッド名に付加し、スクリーンショットを出力している場合はスクリーンショットファイル名にシナリオ番号、ケース番号を付加して紐付けるようにする。
運用
開発フェーズ以降のJenkinsを使用したクラスパスmain以下のJavadoc出力
開発期間中は毎日Jenkinsで出力する。
クラス図を一緒に出力する事。
クラスパスtest(単体テストソース)以下のJavadoc出力
開発期間中は毎日Jenkinsで出力する。
クラス図の出力は任意。
selenium, appiumによるテストプロジェクトのxmlリスト出力
顧客の意向で結合テスト内容等はExcelでの提出を強制されるような場合は
Javadoc⇒xml⇒Excel等のフォーマット
と出力する必要がある。Jenkinsで定期的に実行。
ここが一番手間。
Excel等のフォーマットに取り込む際は、テスト結果も取り込めるようにしておく。seleniumとJavaDocの使用で内部結合テスト以降の工数はかなり削減できる。
※なぜかJavadocをxmlで出力するドックレットが見つからないので自作するしかないみたい。Doxygenだったらxml出力できるのでここだけDoxygen使って出力するか。
また、xmlからExcel等のフォーマットに取り込むのは別途マクロ作成。Java等の開発で使用している言語使って直接ドキュメント出力するのも有りだけど他プロジェクトに応用が利くようにelectronとかC#でWindowsアプリ作った方がいいのかな。
Checkstyleの設定
残念なことだが、コーディングが好きな開発者もJavadocは面倒くさがって書きたがらない人が多い。いくら手順化しても漏れてしまうことが多々ある。ということでCheckstyleにJavadocのチェックを入れる。
Checkstyleはchefで配布するようにし、同様の設定でJenkinsで定期的にチェックする。
参考(近日公開予定)：[Eclipse CheckStyle サンプル]
redmineの設定
Jenkinsで定期的に出力したJavadocをredmineのwiki等からリンクしておく。テスト関連のJavadocは生成したドキュメントをダウンロードできるようにしておく。他のドキュメント類も含めてredmineから全てリンクし一元管理する事が理想。