Help us understand the problem. What is going on with this article?

Javadocの概要ページ設定

More than 3 years have passed since last update.

JavaDocの先頭ページにプロジェクトの概要を表示する方法とJavadocにpackageの情報ページを入れる方法です。Javadocを公開する場合は必須、テストソースのjavadocの場合はテスト観点や目的、結果を乗せるページとなるので割と重要。
プロジェクト概要ページは構成管理者、パッケージ情報ページはそのパッケージの開発者が作成時にまとめるルールが必要でしょう。特にパッケージ情報は忘れがちなのでCheckstyleでチェックした方がいいかも。

プロジェクト概要

プロジェクト概要ページは開発の最初に作成してしまえば特にメンテナンスをする必要もないので是非作成してほしいところ。

1. 以下のようなhtmlファイル(名前は任意。例:overview.html)を作成し、任意の場所に保存する(通常はJavadoc生成対象のルートディレクトリとかに置くのがよいかも)。
Javadocの概要ページには<body>タグの中身が表示される。

overview.html
<!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>

image1.png

2. Javadocコマンドのオプション-overviewでこのファイルを指定する。
Eclipseの場合はパッケージエクスプローラの
Javadoc出力フォルダルート右クリック⇒エクスポート⇒Java-Javadoc
のダイヤログの3面目の[追加のJavaオプション]に
-overview D:\xxxx\overview.html
のように設定します。
image2.png
image3.png

3. 結果
赤枠で囲った部分が反映されたところ。
image4.png

パッケージ情報

Javadocではパッケージ毎にそれぞれ説明を入れることができる。通常の業務開発ではあまりありがたみがないが、基盤開発の場合はlib、common、util配下のそれぞれのパッケージの説明がかなり重要になる。
seleniumのテストソースの場合等は機能毎にパッケージを分けて作成し、それぞれのパッケージ情報にテストする機能概要、観点等を記載しておけばテスト仕様書の作成が楽になるかも。

1. 説明を付与したいパッケージのディレクトリの直下に「package-info.java」という名前で配置する。
image5.png

2. package-info.javaにJavadocで説明を記載する。Javadoc生成時は特にオプションの指定の必要はない。

package-info.java
/**
 * 最初の文はタイトルの直下にも表示されます。
 * 説明本文です。ここでは一般的なHTMLタグが使用できます。
 */
package hogehoge.hugahuga.burabura;

3. 結果
トップページ
image6.png

パッケージの先頭ページ
image7.png

Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
ユーザーは見つかりませんでした