Javadoc

出典: フリー百科事典『ウィキペディア（Wikipedia）』

Javadocとは、サン・マイクロシステムズが開発したコンピュータソフトで、JavaのソースコードからHTML形式のAPI仕様書を生成する。

JavadocはJavaクラスの仕様書の標準の書式であり、多くのIDEは自動的にJavadoc HTMLを生成する機能を備えている。

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

[編集] Javadocのタグ

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

Tag	Description
@author	開発者名を記述する。
@deprecated	廃止されたクラス (コンピュータ)やメソッドに付けられる。コンパイル時にこれがつけられたメソッドを使用すると警告を発する。IDEによっては、このマークがつけられたメソッドを使用したコーディングをした場合、警告を発する。Java SE 5以降からは、アノテーションを用いて同様のことができるようになっている。
@exception	メソッドが投げる例外クラスとその説明を記述する。— @throwsも参照。
@param	メソッドの引数や総称型のパラメータを記述する。引数の数だけ記述する必要がある。引数名と引数の概要を記述する。
@return	メソッドの戻り値を記述する。戻り値がvoidの時は記述しなくて良い。
@returns	@returnと同じ。
@see	関連する他のメソッドまたはクラスを記述する。このタグの内容は自力で記述するのは大変なのでIDEなどで自動生成すると良い。
@since	クラスまたはメソッドの導入されたバージョンを記述する。IDEなどの自動生成ツールでここに日付やバージョン番号などの情報をわりあてることができる。
@throws	メソッドが投げる例外を記述する。@exceptionと同義。Javadoc 1.2.で追加された。
@version	クラスまたはメソッドのバージョンを記述する。バージョン管理システムを用いてこのバージョン番号割り当てを自動化することができる。
{@link}	標準テキストのラベルとインラインリンクを挿入する。{パッケージ名.クラス名#メソッド名 label}という方式で記述。labelの文法は@seeと同じ。
{@docRoot}	生成されたドキュメントのルートディレクトリを基点とする相対パスを表す。
@serial	デフォルトで直列化可能フィールドのdocコメントで使用する。このタグの後に説明を入れる。これは直列化形式ページの生成に使われる。
@serialField	`Serializable`クラスのObjectStreamField コンポーネントをドキュメント化する。各 ObjectStreamField コンポーネントに対して @serialField タグを 1 つ使う必要がある。このタグの後に、順番にフィールド名、フィールドの型、フィールドの説明を記述する。
@serialData	データの型と順序を直列化形式でドキュメント化。このデータには、特に writeObject メソッドによって書き込まれる任意指定のデータ、および `Externalizable#writeExternal(ObjectOutput)` メソッドによって書き込まれるすべてのデータが含まれる。@serialData タグは、`writeObject(Object)`、`readObject()`、`writeExternal(ObjectOutput)`、および `readExternal(ObjectInput)`の各メソッドの doc コメントで使用できる。このタグの後に説明を記述する。

[編集] 例

Javadocの使用例。（サンプルには英語が含まれているが、日本語の使用も可能）。

/**
 * クラスの説明.
 * <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 このメソッドは非推奨です。
   * @param t 説明
   * @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全体の概要を説明するコメントファイルや画像ファイルを参照することができる。

[編集] パッケージコメントファイル

各パッケージ (Java)ディレクトリにpackage.htmlというファイルを置くことで、各パッケージの説明を記述することもできる。ほかに、ドキュメント全体の概要を示す概要コメントファイル(overview.html)を記述することもできる。これらの文法は以下のような簡単なHTMLとなる。

<html>
  <body>
    ここにパッケージの概要を記述する。
  </body>
</html>

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

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

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

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

[編集] 未処理ファイル

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から登場したアノテーションが代わりの役目を果たしてくれることもあり、徐々に使われなくなっていくと予想される。

[編集] 関連項目

ウィキブックスにJava関連の教科書や解説書があります。

[編集] 外部リンク

表・話・編・歴 Java（カテゴリ）
主要技術	プログラミング言語Java - Javaプラットフォーム - Java Development Kit - Java仮想マシン - Java Runtime Environment - Javaコンパイラ - Javaバイトコード - JAR
歴史	Javaに対する批判 - Java Community Process - サン・マイクロシステムズ
言語機能	文法 - Javaの予約語 - パッケージ - Javadoc
関連技術	Jakarta Project - Apache Tomcat - NetBeans - Java Beans - Java Message Service - Java Transaction API - Java3D - JDBC - Java Web Start - Applet - Servlet - JavaServer Pages - Java Foundation Classes

カテゴリ: ソフトウェア開発ツール | Javaツール | Java specification requests

See also ebooksgratis.com: no banners, no cookies, totally FREE.