ja Javadoc

Javadocとは、サン・マイクロシステムズが開発したコンピュータソフトウェアのひとつで、JavaのソースコードからHTML形式のAPI 仕様書を生成するプログラミングツールである^[1]。広義ではJavadocに対応した形式のコメントを指す。

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

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

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

サンはのちにオラクルに買収されたが、Javadocに関するドキュメントもオラクルに移管されている。

Javadocのタグ

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

タグ	記述内容
@author	開発者名を記述する。
@deprecated	非推奨（廃止予定）となったクラスやメソッドに付ける。これが付けられたクラスやメソッドを使用しているコードがある場合、コンパイル時に警告を発する。IDEの多くは、コンパイルする前にコードエディター上でも警告を発する。Java SE 5以降からは、`@Deprecated`アノテーションを用いて同様のことができるようになっている。@deprecatedでドキュメント化されているが`@Deprecated`アノテーションがない場合、javacコンパイラからdep-annの警告が生成される^[3]。
@exception	メソッドが投げる例外クラスとその説明を記述する。@throwsも参照。
@param	メソッドの引数や総称型のパラメータを記述する。引数の数だけ記述する必要がある。引数名と引数の概要を記述する。
@return	メソッドの戻り値を記述する。戻り値がvoidのときは記述しなくてよい。
@returns	@returnと同じ。
@see	関連する項目を記述する。形式は3種類あり^[1]、二重引用符で囲まれた任意の文字列（書籍名など）、HTMLのアンカー要素を使った任意のハイパーリンク、あるいはプログラム要素（クラスやメソッドなど）の名前とオプションのラベルを記述する。このタグの内容は自力で記述するのは煩雑なので、IDEなどで自動生成するとよい。
@since	クラスまたはメソッドの導入されたバージョンを記述する。IDEなどの自動生成ツールでここに日付やバージョン番号などの情報を割り当てることができる。
@throws	JDK 1.2で導入された。メソッドが投げる例外を記述する。@exceptionと同義。
@version	クラスまたはメソッドのバージョンを記述する。バージョン管理システムを用いてこのバージョン番号割り当てを自動化することができる。
{@link}	JDK 1.2で導入された。標準テキストのラベルとインラインリンクを挿入する。`{@link package.class#member label}`という形式で記述する。labelの文法は@seeと同じ。
{@docRoot}	生成されたドキュメントのルートディレクトリを基点とする相対パスを表す。
@serial	デフォルトで直列化可能フィールドのdocコメントで使用する。このタグの後に説明を入れる。これは直列化形式ページの生成に使われる。
@serialField	`Serializable`クラスの`ObjectStreamField`コンポーネントをドキュメント化する。各`ObjectStreamField`コンポーネントに対して @serialField タグを1つ使う必要がある。このタグの後に、順番にフィールド名、フィールドの型、フィールドの説明を記述する。
@serialData	データの型と順序を直列化形式でドキュメント化。このデータには、特に`writeObject`メソッドによって書き込まれる任意指定のデータ、および `Externalizable.writeExternal(ObjectOutput)` メソッドによって書き込まれるすべてのデータが含まれる。@serialData タグは、`ObjectOutput.writeObject(Object)`、`ObjectInput.readObject()`、`writeExternal(ObjectOutput)`、および `readExternal(ObjectInput)`の各メソッドの doc コメントで使用できる。このタグの後に説明を記述する。

例

Javadocコメントの記述例。サンプルには英語が含まれているが、適切なテキストエンコーディング（通例UTF-8）を使用することで日本語の使用も可能である。

 /**
  * クラスの説明.
  * <pre>
  * ピリオド(.)または句点(。)で終わるところまでが、
  * クラス一覧の概要に説明されるところであり、
  * ピリオド以降は説明の概要には含まれず、クラスの説明に含まれる。
  * このように、JavadocにはHTMLタグを使用することができる。
  * </pre>
  * @param <T1> 総称型パラメータの説明
  * @param <T2> 総称型パラメータの説明
  * @author Wikipedian
  * @author Second author
  * @version 1.6
  * @since 1.0
  */
 public class JavadocSample<T1, T2 extends List> {
 
   /**
    * @serial 直列化可能データの説明
    */
   private int x;
 
   /**
    * Validates a chess move.
    * @author John Doe
    * @param theFromFile File of piece being moved
    * @param theFromRank Rank of piece being moved
    * @param theToFile   File of destination square
    * @param theToRank   Rank of destination square
    * @return true if a valid chess move or false if invalid
    */
   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となる。

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

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

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

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

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

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

未処理ファイル

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

/**
 * 画像ファイル
 * <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から登場したアノテーションで代替することが可能になった。

脚注

出典

外部リンク

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

[javase8_javadoc-1] vadoc | Oracle Java SE 8

[2] Javadoc | IntelliJ IDEA ドキュメント

[3] vac | Oracle Java SE 8

[1]

[2]

[3]

Javadoc