Javadoc

Javadocとは

Javadocは、JavaのソースコードからAPIドキュメントを生成するツールです。サン・マイクロシステムズによって開発され、現在はオラクルに移管されています。このツールは、Java Development Kit (JDK) や OpenJDK に含まれるコマンドラインツールとして提供されていますが、多くの統合開発環境 (IDE) からもGUIで操作できます。

Javadocの役割

Javadocは、Javaクラスの仕様書を作成するための標準的な書式を提供します。IDEによっては、Javadocコメントの記述を支援する機能や、ドキュメントのプレビュー表示機能も備わっています。生成されるドキュメントは標準でHTML形式ですが、カスタマイズすることも可能です。

Javadocタグ

開発者は、ソースコードに特定の形式でコメントを記述する際にJavadocタグを使用します。`/*`で始まるコメントがHTMLドキュメントに反映され、タグは`@`記号で始まります。これらのタグを使って、クラス、メソッド、フィールドなどの情報を記述します。

コメント記述例

Javadocコメントは、日本語を含めて記述できます。適切なテキストエンコーディング（通常はUTF-8）を使用することで、多言語に対応したドキュメントを生成できます。

ドキュメント生成

Javadocは、Javadocコメントだけでなく、パッケージやAPI全体の概要を説明するコメントファイルや画像ファイルも参照できます。

概要コメントファイル

`overview.html`ファイルに、ドキュメント全体の概要を記述できます。これは簡単なHTMLで記述され、Javadocコマンド実行時に`-overview`オプションで指定するか、ソースツリーのルートに配置することでドキュメントに含められます。

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

`package-info.java`ファイルに、パッケージに関するコメントを記述できます。これは、クラスやメソッドにJavadocコメントを記述するのと同じ形式で記述でき、アノテーションも使用できます。`package.html`ファイルよりも`package-info.java`の使用が推奨されています。

未処理ファイル

ドキュメントに画像を含めるには、画像を置くディレクトリを作成し、Javadocコメントでリンクを記述します。画像ファイルは、クラスがあるディレクトリの`doc-files`ディレクトリに配置します。

Javadoc生成を容易にするツール

Javadocの生成は、設定が複雑になることがありますが、IDEやApache Ant、Apache Mavenなどのツールを使用することで、容易に生成できます。

Doclet

Javadocには、JavadocタグをカスタマイズできるDocletという機能があります。これを利用して、設定ファイルの内容をJavadocコメントとして記述したり、他のJavaソースコードやデータベーススキーマを自動生成したりすることが可能です。ただし、Java SE 5以降では、アノテーションで代替できる機能も多くなっています。

まとめ

Javadocは、Java開発における重要なドキュメンテーションツールです。APIドキュメントの標準化、開発効率の向上、そして、ソフトウェアの理解促進に貢献しています。柔軟なカスタマイズ性、さまざまなツールとの連携により、開発プロセスを効率化できるでしょう。

脚注

出典：Javadocテクノロジ

関連項目

文芸的プログラミング
アノテーション
Javaの文法
ソフトウェアドキュメンテーション
Doxygen

外部リンク

Javadocテクノロジ
ドックレット API
JSR 260: JavadocTM Tag Technology Update （英語）

もう一度検索