Javadocで日本語APIリファレンスを作る

Javaに付属のコマンドツールに「javadoc」というのがあります。
このコマンドにより，JavaのソースファイルからHTML形式のAPIリファレンスを自動生成することができます。
Sunが公開しているJava組み込みクラスのAPIリファレンスは，Javadocで生成したAPIリファレンスの一例です。

Javadocはデフォルトで英語のソースファイルから英語のドキュメントを生成しようとします。
Javadocで日本語のドキュメントを生成するには，Javadocのコマンド実行時に以下のオプション指定を行います。

１）Javadocが生成するメッセージを英語から日本語にしたい。
→Javadocのコマンドオプションで，
「-locale ja」
と指定することで，ドキュメントのナビゲーションバーなどのメッセージが日本語になります。このメッセージの文字コードは，下記４）のオプション指定で決まります。
このロケールについての解説は「java.util.Locale」を参照。また，ここで指定できる言語コードのリストはこちらを参照。

２）生成されるHTMLファイルのヘッダで文字コード指定を行いたい。
→Javadocのコマンドオプションで，
「-charset "文字セット名"」（注：文字セット名はダブルクォーテーションで囲む）
を指定することで，ドキュメントのHTMLヘッダに

<meta http-equiv="Content-Type" content="text/html; charset=文字セット名">

の行が付加されます。
ここで指定できる日本語の文字セット名には「Shift_JIS」「euc-jp」「iso-2022-jp」「utf-8」「Windows-31J」があります。
ここで指定する文字セット名は下記４）の文字エンコーディング名と合わせる必要があります。HTMLヘッダにこの行を付加しない場合はブラウザのデフォルト値が適用されます。
ここで指定できる文字セット名のリストはこちらを参照。

３）Javaソースファイルの文字コードを指定したい。
→Javadocのコマンドオプションで，
「-encoding 文字エンコーディング名」
を指定します。これと下記４）との組み合わせで，ソースファイル内の文字列をHTMLに出力するときの文字コード変換の内容が決まります。
指定可能な文字エンコーディング：[Java 1.4][Java 1.5]

４）出力するHTMLファイルの文字コードを指定したい。
→Javadocのコマンドオプションで，
「-docencoding 文字エンコーディング名」
を指定します。これにより，上記１）の日本語メッセージの文字コードが決まります。また，上記３）との組み合わせで，ソースファイル内の文字列をHTMLに出力するときの文字コード変換の内容が決まります。
指定可能な文字エンコーディング：[Java 1.4][Java 1.5]

コマンド実行例：UTF-8のソースファイルからSJISのドキュメントを生成する。

javadoc -locale ja -charset "Shift_JIS" -encoding UTF-8 -docencoding SJIS -d docs -private *.java

（「-d docs」は出力ディレクトリに「docs」を指定，「-private」はprivateなクラスやメソッドのリファレンスも出力）

■関連情報
Javadocの基本的な使い方（JavaでHelloWorld）
Sun：Javadocのドキュメント[Solaris版][Windows版]
Java：Shift_JISのエイリアスの変更について

■関連書籍をAmazonで検索：[Java]
●エンジニアのためのJavadoc再入門講座 現場で使えるAPI仕様書の作り方



　　　←この記事が役に立ったという方はクリックお願いします。

---