Javadoc

**Javadoc**とは、オラクルが開発しているコンピュータソフトウェアのひとつで、JavaのソースコードからHTML形式のAPI仕様書を生成するプログラミングツールである。広義ではJavadocに対応した形式のコメントを指す。

Javaのソフトウェア開発キットのJava Development Kit (OpenJDKやOracle JDKなど) に含まれるCUI/CLIベースのコマンドラインツールであるが、Javaに対応した多くの統合開発環境 (IDE) ではJavadocをGUIから直感的に操作することもできる。

JavadocはJavaクラスの仕様書の標準の書式であり、IDEの中にはJavadocコメントの記述支援機能やドキュメントのプレビュー表示機能などを備えているものもある。

なお、HTML形式は標準の書式であり、カスタマイズにより変更可能である。

サン・マイクロシステムズはのちにオラクルに買収されたが、Javadocに関するドキュメントもオラクルに移管されている。

## Javadocのタグ

開発者はソースコードにコメントを記述するときに、ある程度の決まった形式の文章とJavadocタグを使用する。ソースのコメントのうち、**<code>/**</code>**で始まるものが、生成されたHTMLに含まれることになる。Javadocタグは、頭に`@`（単価記号）が付く。いくつかのタグはテーブル（表）用のものである。

:

## 例
Javadocコメントの記述例。適切なテキストエンコーディング（通例UTF-8）を使用することで日本語の使用も可能である。

```java
/**
  * クラスの説明。
  * <pre>
  * ピリオド(.)または句点(。)で終わるところまでが、
  * クラス一覧の概要に説明されるところであり、
  * ピリオド以降は説明の概要には含まれず、クラスの説明に含まれる。
  * このように、JavadocにはHTMLタグを使用することができる。
  * </pre>
  * @param <T1> 総称型パラメータの説明
  * @param <T2> 総称型パラメータの説明
  * @author Wikipedian
  * @author 作者B
  * @version 1.6
  * @since 1.0
  */
 public class JavadocSample<T1, T2 extends List> {
 
   /**
    * @serial 直列化可能データの説明
    */
   private int x;
 
   /**
    * チェスの指し手（移動）を検証する。
    * @author John Doe
    * @param theFromFile 移動させる駒のファイル（列）
    * @param theFromRank 移動させる駒のランク（行）
    * @param theToFile   移動先のマスのファイル（列）
    * @param theToRank   移動先のマスのランク（行）
    * @return チェスの移動が有効な場合は true、無効な場合は false
    */
   boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
      //...
   }
 
   /**
    * 非推奨メソッド。
    * @deprecated このメソッドは非推奨です。
    * @throws SomeException 例外の説明
    */
   String deprecatedMethod() {
     //...
   }
 
   /**
    * メソッドの説明。
    * @param t 説明
    * @throws SomeException 例外の説明
    * @throws Exception 例外の説明
    * @return String型の値
    * @since 1.5
    * @see "関連"
    * @see <a href="http://www.example.com/">Example</a>
    * @see String#equals(Object) equals
    */
   String add(T1 t) throws SomeException, Exception {
     //...
   }
 }
```


## ドキュメント生成
ドキュメント生成には、これらのJavadocコメントのほかに、パッケージやAPI全体の概要を説明するコメントファイルや画像ファイルを参照することができる。
### 概要コメントファイル
ドキュメント全体の概要を示す概要コメントファイル (overview.html) を記述する。これらの文法は以下のような簡単なHTMLとなる。

```html4strict
<html>
  <body>
    ここに概要コメントを記述する。
  </body>
</html>
```

概要コメントファイル (overview.html) はJavadocコマンド実行時に-overviewオプションでディレクトリパスを指定するか、または、パッケージを置いているソースツリーのルートにoverview.htmlファイルを置くことでドキュメントに含められる。

### パッケージコメントファイル
package-info.javaというファイルにコメントを記述する。JDK 1.4 までは package.html に記載した。これは以下のように、クラスやメソッドなどに記述するJavadocコメントと同じ要領で済む。ただし、packageキーワードを用いてパッケージ宣言しなければならない。

```java
/**
 * ここにパッケージの概要を記述する。
 * @since 1.5
 */
package com.example.wikipedia;
```

この記法は、Java SE 5から登場したアノテーションには、パッケージにも指定できるものがあるために用意された。これにより、package-info.javaにはアノテーションも保存でき、たとえばパッケージに対してアノテーションを指定できるようになった。package.htmlではアノテーションが使用できないため、package-info.javaの使用はpackage.htmlよりも推奨されている。

### 未処理ファイル
Javadocで生成するドキュメンテーションには画像やJavaソースコードなどを含めることもできる。画像を置くには、画像を表示したいクラスがあるディレクトリに*doc-files*という名前のディレクトリを作成し、そこに画像をコピーする。そしてこの画像のリンクを実際に張るには以下のようにJavadocコメントに明示的に記述する必要がある。

```java
/**
 * 画像ファイル
 * <img src="doc-files/image.gif" />
 */
```


## Javadoc生成を容易にするツール
Javadocの生成は、そのままでは複雑なコマンドラインを必要とする。とくに設定を細かくすると、バッチファイルやシェルスクリプトとして記述するだけでも膨大なものになる。そこでNetBeansやEclipseなどのIDEやApache AntのようなビルドツールやApache Mavenのようなプロジェクト管理ツールを使うことが薦められている。

## Doclet
JavadocにはJavadocのタグを自作できる機能Docletがある。これを用いて、Apache Tomcatの設定ファイルweb.xmlの内容をJava ServletソースコードのJavadocコメント上に記述してXDocletを用いてweb.xmlを自動生成するといったことが可能になる。このほかにも、Javadocコメントから他のJavaソースコードやデータベーススキーマやUMLのクラス図を自動生成するといったことが可能になり、開発効率が飛躍的に向上する。

これはEnterprise JavaBeansやApache Struts、UML、Hibernate、JBossなどにも使われている。ただし現在では、これらの多くがJavadocによる自動生成の代わりに、Java SE 5から登場したアノテーションで代替することが可能になった。

## 脚注

### 出典

## 関連項目

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

## 外部リンク
* Javadocテクノロジ
* ドックレット API
* JSR 260: Javadoc<sup>TM</sup> Tag Technology Update