WEB+DB PRESS Vol.51 特集2「“巧い”メソッド設計」連動企画

第1回 Javadocリファレンス

この記事を読むのに必要な時間:およそ 9 分

はじめに

ここでは,WEB+DB PRESS Vol.51特集2「~現場の知恵と経験,絞り出しました~巧いメソッド設計」第7章「~ドキュメントツールJavadoc再入門~Javadocをコード品質の向上に活用しよう」と連動して,「Javadocリファレンス」と題し,Javadocドキュメントにおけるコマンド,タグなどの書き方について解説します。

Javadocドキュメントに含まれるもの

Javadocドキュメントにはパッケージ,クラス,インタフェース,コンストラクタ,メソッド,フィールドなどの情報が含まれます。

Javadocでは,HTMLのタグを利用できます。JavadocツールはHTML 3.2に準拠したコードを生成しますが,フレームに対応するためHTML 4.01の文書として扱われます。どのタグが使えるのかを明記した公式の資料はありません。さまざまなブラウザで読まれることを考慮して使うタグを選択しなければなりません。表1に代表的なHTMLタグを示します。これ以外のタグを使う必要はないと思います。また,<H1>~<H6>,<HR>タグはJavadocの文書構造を壊す可能性があるので使用してはいけません。

表1 Javadocで使用するHTMLタグ

内容タグ
リンク・画像<A>,<IMG>
段落・改行<P>,<BR>
リスト<UL>,<OL>,<LI>
強調<B>,<I>
テーブル<TABLE>,<TR>,<TH>,<TD>

ドキュメントコメントの構造

ドキュメントコメントは主説明とタグセクションの2つで構成されます。主説明にはクラスやメソッドの責務や制約,使用例などを記述します。タグセクションには@で始まるドキュメントタグを記述し,パラメータや戻り値などの説明を行います図1図2)。

図1 ドキュメントコメントの記述例

図1 ドキュメントコメントの記述例

図2 ドキュメントコメントの出力例

図2 ドキュメントコメントの出力例

最初の文

主説明の最初の文は概要としてコピーされる簡潔な要約文です。パッケージの概要は,概要ページの概要テーブル,クラスの概要はパッケージページの概要テーブルにコピーされます。

最初の文は,次の条件で文が終了したと判定されます。

  • 。(句点)が見つかった場合
  • 感嘆符や疑問符が見つかった場合
  • 後ろに空白,タグ,行末記号が続くピリオドが見つかった場合
  • 主説明の最後まで,区切りが見つからなかった場合

上記の区切り文字を最初の文で使う場合は,HTMLの数値文字参照を使ってエスケープします。

  • 例:ピリオド(.) → &#x2E;

コメントの記述

Javadocで使用するドキュメントコメントファイルは表2のように4つに分けることができます。それぞれについてどういう内容を記述するのかを説明していきます。説明の例に標準ライブラリのクラス名やメソッド名を示しているものがいくつかあります。JDKJava Development KitのJavadocは良質なコメントが多いので,実際にどのように記述しているかを参考にしてください。

表2 ドキュメントコメントファイル

ソースファイル内容ファイル名ディレクトリ
概要コメントファイルアプリケーションまたはパッケージセットに対してのコメントoverview.htmlソースディレクトリのルート
パッケージコメントファイルパッケージに対してのコメントpackage-info.javaパッケージディレクトリ
クラスソースファイルクラス,フィールド,メソッドに対してのコメント*.javaパッケージディレクトリ
その他(画像など)画像やDemoファイル,PDFファイルなど*.*パッケージディレクトリ/doc-files

javadocコマンドの-overviewオプションで指定するため,任意の名前で作成できます。

概要コメントファイル

アプリケーションまたはパッケージセットに対してのコメントファイルですリスト1図3)。概要コメントファイルはHTMLファイルとして作成します。公開ドキュメント用と内部向けドキュメント用の2つの概要コメントファイルを切り替えて使うことをお勧めします。

リスト1 概要コメントファイル(overview.html)

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
  <head>
    <title></title>
    <meta http-equiv="Content-Type" content="text/html; charset=Shift_JIS">
  </head>
  <body>
    公開用の概要ファイルです。&lt;BODY&gt;タグの中身が概要コメントとして概要ファイルの最後にコピーされます。
    最初の文は概要ファイルの最初にもコピーされます。
    <P>
        概要コメントファイルには以下のような内容を記述します。
    <UL>
       <LI>アプリケーションまたはパッケージセットの全体に適用される内容
       <LI>使用している標準や規格などの説明,詳細情報へのリンク
       <LI>使用方法についての簡単な説明やサンプルコード
    </UL>
<!-- 内部向けであれば以下の内容も記述する
    <UL>
       <LI>アーキテクチャを採用した背景
       <LI>関連するシステムの情報。他システムとの連携の方法など。
    </UL>
-->
  </body>
</html>

図3 概要コメントファイルの出力例

図3 概要コメントファイルの出力例

パッケージコメントファイル

パッケージに対してのコメントファイルですリスト2図4)。パッケージの説明はパッケージページの最後にコピーされます。最初の文は概要ページの概要テーブルとパッケージページの先頭にコピーされます。

リスト2 パッケージコメントファイル(package-info.java)注1

/**
 * webdb51パッケージの説明を記述します。
 * <P>
 * パッケージコメントファイルには以下の内容を記述します。
 * <UL>
 * <LI>パッケージが提供する機能についての説明
 * <LI>パッケージを使用するときにキーとなるオブジェクトの説明
 * <LI>パッケージ内のクラスの分類や重要な用語の説明。例)java.netパッケージ
 * <LI>OSやハードウェアへの依存性
 * <LI>外部仕様への参照。例)java.utilパッケージ
 * </UL>
 */
package webdb51;

図4 パッケージコメントの出力例

図4 パッケージコメントの出力例

注1)
package-info.javaは有効なクラス名ではないため,IDEで作成する場合はクラスとしてではなく,通常ファイルとして作成する必要があります。

著者プロフィール

小棚木章直(おだなぎあきなお)

(株)富士通ビー・エス・シーに勤務しているソフトウェアエンジニア。主にJava読書会で活動。アジャイル開発に興味があり,XPJUGのイベントに参加することも多い。最近はバグパターンをテーマにしている。

コメント

コメントの記入