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 <T> 総称型パラメータの説明 * @param <?> 総称型パラメータの説明 * @author Wikipedian * @author Second author * @version 1.6 * @since 1.0 */ public class JavadocSample<T, ? 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(T 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から登場したアノテーションが代わりの役目を果たしてくれることもわり、徐々に使われなくなっていくと予想される。
[編集] 関連項目
[編集] 外部リンク
- Javadocテクノロジ
- ドックレット API
- How to Write Doc Comments for the Javadoc Tool
- JSR 260 Javadoc Tag Technology Update Java Specification Request (defines new Javadoc tags)
- Improve on Javadocs with ashkelon
- A collection of Javadoc doclets
- An index to many Javadoc generated websites
- JavadocOnline: Search engine project, to get public Javadocs over Internet
- DocJar: Another search engine project, to get public Javadocs over Internet
- Globaldocs: A viewer to browse multiple Javadocs simultaneously.
- Various Java documentations converted to Windows Help format
| Java | |
|---|---|
| 主要 テクノロジ |
Java言語 | Javaプラットフォーム | Java Development Kit | Java仮想マシン | Java Runtime Environment | Javaコンパイラ | Enterprise JavaBeans | Java Message Service | Java Transaction API | Java3D | JDBC | Java Web Start |
| 歴史 | Javaバージョンの歴史 | Java批評 | Java Community Process | サン・マイクロシステムズ |
| 言語機能 | バイトコード | 文法 | Applet | Servlet | JavaServer Pages | Java Foundation Classes | Java予約語 | パッケージ | JAR | Javadoc |
| Java関連技術 | Jakarta Project | Apache Tomcat | NetBeans |
