Javadoc
とは、
サン?マイクロシステムズ
が開?したコンピュ?タソフトで、
Java
のソ?スコ?ドから
HTML
形式の
API
仕?書
を生成するものである。
JavadocはJavaクラスの仕?書の標準の書式であり、多くの
IDE
は自動的にJavadoc HTMLを生成する機能を備えている。
なお、HTML形式は標準の書式であり、カスタマイズにより?更可能である。
Javadocのタグ
[
編集
]
開?者はソ?スコ?ドにコメントを記述する時に、ある程度の決まった形式の文章とJavadocタグを使用する。ソ?スのコメントの?、
/**
で始まるものが、生成されたHTMLに含まれることになる。Javadocタグは、頭に"@" 記?が付く。いくつかのタグはテ?ブル用のものである。
| タグ
|
記述?容
|
| @author
|
開?者名を記述する。
|
| @deprecated
|
?止された
クラス
や
メソッド
に付けられる。コンパイル時にこれがつけられたメソッドを使用すると警告を?する。
IDE
によっては、このマ?クがつけられたメソッドを使用したコ?ディングをした場合、警告を?する。
Java SE
5以降からは、
@Deprecated
アノテ?ション
を用いて同?のことができるようになっている。
|
| @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全?の?要を?明するコメントファイルや?像ファイルを?照することができる。
?要コメントファイル
[
編集
]
ドキュメント全?の?要を示す?要コメントファイル (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から登場した
アノテ?ション
で代替することが可能になった。
?連項目
[
編集
]
ウィキブックスに
Java
?連の解?書??科書があります。
外部リンク
[
編集
]
|
|---|
| プラットフォ?ム
| | |
|---|
| オラクルのテクノロジ?
| |
|---|
| プラットフォ?ム技術
| |
|---|
| 主なサ?ドパ?ティ技術
| |
|---|
| ?史
| |
|---|
| 主要なJVM言語
| |
|---|
| コミュニティ
|
|
|---|
|
|