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

第1回　Javadocリファレンス

2009年6月29日

初出：WEB+DB PRESS Vol.51（2009年6月24日発売）

小棚木章直

メソッド, Javadoc, WEB+DB PRESS, コード

パッケージ, ドキュメント, package, フィールド, メソッド

はじめに

ここでは，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　ドキュメントコメントの記述例

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

最初の文

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

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

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

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

例：ピリオド（.） → .

コメントの記述

Javadocで使用するドキュメントコメントファイルは表2のように4つに分けることができます。それぞれについてどういう内容を記述するのかを説明していきます。説明の例に標準ライブラリのクラス名やメソッド名を示しているものがいくつかあります。JDK（Java 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　概要コメントファイルの出力例

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

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

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

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

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

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

メソッド, Javadoc, WEB+DB PRESS, コード

小棚木章直（おだなぎあきなお）

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

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

第３回　構造化技法でプログラムの品質を上げる　可読性の高いメソッドを書くための実践テクニック
第2回　潜在するバグに対処するための　エラー処理の考え方
第1回　Javadocリファレンス

このエントリのトラックバック URI

お名前
メールアドレス
タイトル
コメント

多数の情報処理技術者試験対策書籍の発行実績を誇る技術評論社がお届けする，資格試験合格サイト「めざせ！情報処理試験パスサポ」が開設されました。

サクセスストーリーに続く，快適サーバー運用管理のヒント！: データの増大，煩雑な管理，システムダウン，セキュリティなど，迫りくる課題からシステム管理者の負担を軽くするポイントを解説します。
gihyo.jp インフラエンジニア情報局: ネットワークやITにかかわるあらゆる業種で必要とされるインフラエンジニアに向けた技術情報や心構え，その魅力について多角的に紹介。
テストエンジニアステーション: いま，ITに関わるあらゆる開発業務で注目されつつあるテスト系エンジニアをターゲットにしたコンテンツサイトを展開します。

※検索はページ右上の検索ボックスをご利用ください。

最新ソフトウェアプロテクションの導入方法（3/8～4/16）
Adobe FLASH PLATFORM CAMP Tokyo（3/16）
「組込みデータベースを利用した開発のポイントとDeviceSQLのご紹介」セミナー（3/17）

読むウェブ～本とインタラクション: ディスプレイで読む活字とそのインタラクション（interaction：相互作用）について，最新Webを紹介しながら読み解いていく。
いま，見ておきたいウェブサイト: この連載では，国内外の最新のウェブサイトを隔週更新で取り上げ，これら最新サイトの特徴や素晴らしい部分を，さまざまな角度から解説していきます。
Windows phoneアプリケーション開発入門: Windows Marcketplace for Mobileがサービス開始され，作成したアプリケーションを個人でも世界をターゲットに公開できる環境が整ってきました。これを機にWindows phoneアプリケーションの開発をしてみませんか？
ここは知っておくべき！Windows Server 2008技術TIPS: 5年ぶりのサーバOSとなったWindows Server 2008が出荷されて早2年。2009年にはR2が出荷され，再び注目を集めています。発売前から実施したトレーニングによって感じた，インフラエンジニアの方々に知っておいていただきたい機能を中心にご紹介します。
キーパーソンが見るWeb業界: 本連載はWeb Site Expert／gihyo.jpとの連動企画です。阿部淳也, 長谷川敦士, 森田雄のお三方による，Web業界をテーマにした座談会です。
きたみりゅうじの聞かせて珍プレー: ソフトウェア開発の現場で体験したトホホな失敗，思わずうなる珍プレーをきたみりゅうじ氏が四コママンガで紹介。みなさんからの投稿もお待ちしてます！
ActionScript 3.0で始めるオブジェクト指向スクリプティング: 野中文雄氏が，簡単なスクリプトは書いたことがあるという初級者を対象に，ActionScript 3.0の基本からクラス定義までを解説します。
まだ間に合う「ITパスポート」受験対策　原山先生の短期合格塾: この連載では，4月18日のITパスポート試験の受験に向けて，短い期間で効率良く受験対策を行う方法や，確実に得点するための裏ワザなどを伝授していきます。