Javadoc
Javadocとは、Java言語によって記述されたクラスライブラリやアプリケーションに関するパッケージやクラスやメソッドに関するHTML形式のAPI仕様書のことである。
通常、Javadocは、JDKなどに付属した専用の「javadoc」コマンドを使って生成することができる。またApache AntのjavadocタスクやEclipseなどのIDEのメニューなどからで生成することもできる。Javaのソースコードのメソッド、フィールド変数、クラスなどに対してJavadocコメントと呼ばれる専用のフォーマットで説明や使い方などを記述しておけば、結果的にJavadocに反映される。
参照リンク
JavaTM 2 Platform Standard Edition 5.0 API 仕様
Javadoc
出典: フリー百科事典『ウィキペディア（Wikipedia）』 (2024/09/01 21:39 UTC 版)
 | この記事は検証可能な参考文献や出典が全く示されていないか、不十分です。 (2024年9月) |
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から登場したアノテーションで代替することが可能になった。
脚注
出典
関連項目
外部リンク
| プラットフォーム |
|  | |||||
|---|---|---|---|---|---|---|---|
| オラクルのテクノロジー | |||||||
| プラットフォーム技術 |
| ||||||
| 主なサードパーティ技術 | |||||||
| 歴史 |
| ||||||
| 主要なJVM言語 | |||||||
| コミュニティ |
| ||||||
javadoc
出典: フリー百科事典『ウィキペディア（Wikipedia）』 (2021/01/13 01:34 UTC 版)
「Apache Ant」の記事における「javadoc」の解説
JavaソースコードからJavadocドキュメント（Java APIドキュメント）を生成する。
※この「javadoc」の解説は、「Apache Ant」の解説の一部です。
「javadoc」を含む「Apache Ant」の記事については、「Apache Ant」の概要を参照ください。
固有名詞の分類
- Javadocのページへのリンク
