JavaDocの先頭ページにプロジェクトの概要を表示する方法とJavadocにpackageの情報ページを入れる方法です。Javadocを公開する場合は必須、テストソースのjavadocの場合はテスト観点や目的、結果を乗せるページとなるので割と重要。
プロジェクト概要ページは構成管理者、パッケージ情報ページはそのパッケージの開発者が作成時にまとめるルールが必要でしょう。特にパッケージ情報は忘れがちなのでCheckstyleでチェックした方がいいかも。
プロジェクト概要
プロジェクト概要ページは開発の最初に作成してしまえば特にメンテナンスをする必要もないので是非作成してほしいところ。
1. 以下のようなhtmlファイル(名前は任意。例:overview.html)を作成し、任意の場所に保存する(通常はJavadoc生成対象のルートディレクトリとかに置くのがよいかも)。
Javadocの概要ページには<body>タグの中身が表示される。
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title></title>
</head>
<body>
概要コメントファイルの例です。最初の一文は、概要ページの先頭にも表示されます。
<p>
概要コメントファイルには、通常以下のような内容が記述されます。
<ul>
<li>アプリケーション全体の説明
<li>標準、規格等へのリンク
<li>その他もろもろ
</ul>
他にも、テストのJavadocの場合はテストの前提条件、観点等を記載するといいでしょう。
</body>
</html>
2. Javadocコマンドのオプション-overviewでこのファイルを指定する。
Eclipseの場合はパッケージエクスプローラの
Javadoc出力フォルダルート右クリック⇒エクスポート⇒Java-Javadoc
のダイヤログの3面目の[追加のJavaオプション]に
-overview D:\xxxx\overview.html
のように設定します。
パッケージ情報
Javadocではパッケージ毎にそれぞれ説明を入れることができる。通常の業務開発ではあまりありがたみがないが、基盤開発の場合はlib、common、util配下のそれぞれのパッケージの説明がかなり重要になる。
seleniumのテストソースの場合等は機能毎にパッケージを分けて作成し、それぞれのパッケージ情報にテストする機能概要、観点等を記載しておけばテスト仕様書の作成が楽になるかも。
1. 説明を付与したいパッケージのディレクトリの直下に「package-info.java」という名前で配置する。
2. package-info.javaにJavadocで説明を記載する。Javadoc生成時は特にオプションの指定の必要はない。
/**
* 最初の文はタイトルの直下にも表示されます。
* 説明本文です。ここでは一般的なHTMLタグが使用できます。
*/
package hogehoge.hugahuga.burabura;