Javadoc/Javadoc2

説明

javadocツールを使用してコードのドキュメントを生成します。

処理するJavaソースファイルを探すために、ソースディレクトリを再帰的に走査しますが、そのうち包含規則にマッチするものだけがjavadocツールに渡されます。 パッケージ名を選択するためにワイルドカードが使用できるので、冗長さと全体の管理コストを削減することができます。 しかし、このタスクにはjavacタスクのような"変更された"ファイルの概念はありません。 これは、このタスクを実行するごとに、すべてのパッケージを処理することを意味しています。 しかし、一般的に、このタスクをそんなに頻繁に使用することはありません。

このタスクは、javadocのバージョン (1.1、1.2と1.4) が異なっても同様に動作しますが、1.2の属性が1.1のVMで実行する場合に無視されるという明白な制約があります。

注意: javadocはSystem.exit()を呼び出すので、機能に支障を与えずにjavadocをantと同一VM内で実行することはできません。 この理由から、このタスクは常に新たにVMを生成します。 javadocは一般に重いアプリケーションであり、頻繁に実行されることはないので、このオーバヘッドは重要ではありません。

注意: packagelist属性によって、Antファイルとは別にドキュメント化するパッケージのリストを指定することができます。 ただし、build.xmlファイル内ですべてを指定する方が、より実際的です。 javadocのこのオプションが追加されたことにより、通常のmakefileからの移行が容易になっています。 packagelistでリストされているパッケージはチェックされないので、パッケージが失われていたり、壊れている場合でさえも、タスクを実行します。 だから、既存のmakefileから変換したい場合に、このオプションを使用してください。 一旦うまく実行できるようになったら、通常の記法に切り替えるべきです。

DEPRECATION: javadoc2タスクは、単にjavadocタスクを指定するだけで、互換性を保つために残されています。 このタスクは将来のバージョンでは削除される可能性があるので、代わりにjavadocを使用することを強く勧めます。

パラメタ

属性 説明 利用可能環境 必須
sourcepath ソースファイルを探す場所を指定します。 all 少なくとも3つのうち一つか、ネストした<sourcepath><fileset>または<packageset>
sourcepathref ソースファイルを探す場所を任意の場所で定義されたPATHに対する参照を用いて指定します。 all
sourcefiles カンマで区切られたソースファイルの一覧。 all
destdir ファイルの出力先ディレクトリ。 all はい
maxmemory javadocを実行するVMに割り当てる最大メモリ量。 all いいえ
packagenames (ワイルドカードで終了する) パッケージファイルのコンマで区切られたリスト all
packageList 処理するパッケージを含むファイル名。 all いいえ
classpath ユーザのクラスファイルを探す場所の指定。 all いいえ
Bootclasspath ブートストラップクラスローダがロードするクラスファイルの場所をオーバライドします。 1.2 いいえ
classpathref 任意の場所で指定された参照によって、ユーザのクラスファイルを探す場所を指定します。 all いいえ
bootclasspathref 任意の場所で定義したPATHに対する参照によって、ブートストラップクラスローダがロードするクラスファイルの場所をオーバライドします。 1.2 いいえ
Extdirs インストールした拡張の場所をオーバライドします。 1.2 いいえ
Overview HTMLファイルから概要ドキュメントを読み込みます。 1.2 いいえ
access Access mode: one of public, protected, package, or private
アクセス・モード: publicprotectedpackage、またはprivateのどれか
all No (default protected)
Public publicクラスとメンバのみを表示します。 all いいえ
Protected protected/publicクラスとメンバを表示します (デフォルト) all いいえ
Package package/protected/publicクラスとメンバを表示します。 all いいえ
Private すべてのクラスとメンバを表示します。Show all classes and members all いいえ
Old JDK 1.1をエミュレートするdocletを使用して出力を生成します。 1.2 いいえ
Verbose Javadocの動作状況についてのメッセージを出力します。 1.2 いいえ
Locale 使用するロケール。例、en_US や en_US_WIN 1.2 いいえ
Encoding ソースファイルエンコーディング名。 all いいえ
Version @versionパラグラフを含めます。 all いいえ
Use クラスとパッケージの使用方法のページを作成します。 1.2 いいえ
Author @authorパラグラフを含めます。 all いいえ
Splitindex 索引を一文字に対して一つのファイルに分割します。 1.2 いいえ
Windowtitle ドキュメントのブラウザのウィンドウの題名。(テキスト) 1.2 いいえ
Doctitle パッケージの索引の(最初の)ページに題名を含めます (HTMLコード) 1.2 いいえ
Header 各ページにヘッダのテキストを含めます。(HTMLコード) 1.2 いいえ
Footer 各ページにフッタのテキストを含めます。(HTMLコード) 1.2 いいえ
bottom 各ページの下部にテキストを含めます。(HTMLコード) 1.2 いいえ
link 指定されたURLでjavadoc出力にリンクを作成します。 1.2 いいえ
linkoffline <url2>にあるパッケージリストを用いて、<URL>のdocsにリンクを作成します。 1.2 いいえ
group 指定したパッケージを概要ページで一緒にグループ化します。 1.2 いいえ
nodeprecated @deprecated情報を含めません。 all いいえ
nodeprecatedlist 推奨されないリストを生成しません。 1.2 いいえ
notree クラス階層を生成しません。 all いいえ
noindex 索引を生成しません。 all いいえ
nohelp ヘルプのリンクを生成しません。 1.2 いいえ
nonavbar ナビゲーションバーを生成しません。 1.2 いいえ
serialwarn FUTURE: @serialタグについての警告を生成します。 1.2 いいえ
helpfile FUTURE: 使用するHTMLのヘルプファイルを指定します。 1.2 いいえ
stylesheetfile 使用するCSSスタイルシートを指定します。 1.2 いいえ
charset FUTURE: 生成したドキュメントをクロスプラットフォームで閲覧するためのcharset。 1.2 いいえ
docencoding 出力ファイルのエンコーディング名。 1.1 いいえ
doclet ドキュメントを生成するために使用するdocletを起動するクラスファイルを指定します。 1.2 いいえ
docletpath -docletオプションと一緒に指定するdocletクラスファイルへのパスを指定します。 1.2 いいえ
docletpathref 任意の場所で定義されたPATHに対する参照によって、-docletオプションと一緒に指定するdocletクラスファイルへのパスを指定します。 1.2 いいえ
additionalparam javadocコマンドラインに追加するパラメタを追加します。 docletsにとって便利です。 1.2 いいえ
failonerror コマンドが0以外の返り値で終了した場合には、ビルドプロセスを停止します。 all いいえ
excludepackagenames comma separated list of packages you don't want docs for.
カンマで区切られた、ドキュメントを作成したくないパッケージのリスト。
all いいえ
defaultexcludes indicates whether default excludes should be used (yes | no); default excludes are used when omitted.
デフォルトの除外を使うかどうか(yes | no)。省略時は、デフォルトの除外は使われる。
all いいえ
useexternalfile indicates whether the sourcefile name specified in srcfiles or as nested source elements should be written to a temporary file to make the command line shorter. Also applies to the package names specified via the packagenames attribute or nested package elements. (yes | no). Default is no.
srcfiles、あるいはネストしたsource要素で指定されたソースファイル名が、コマンドラインを    短縮するために一時ファイルに書き込まれるかどうかを示す。これはまた、packagenames属性    あるいはネストしたパッケージ要素により指定されたパッケージ名についても適用される。 (yes | no). デフォルトはno。  
1.2+ No
source Necessary to enable javadoc to handle assertions present in J2SE v 1.4 source code. Set this to "1.4" to documents code that compiles using "javac -source 1.4". Will be ignored if you use a custom doclet.
J2SE バージョン1.4のソースコードに存在するアサーションを、javadocに処理させる必要があるかどうかを指定する。 "javac -source 1.4"としてコンパイルする必要があるソースコード(つまり、アサーションを含むソース)を文書化する場合、この値を"1.4"とする必要がある。 [訳注:javadoc 1.4の新機能を参照]
カスタムDocletを使った場合には無視される。
1.4 No

ネストした要素として指定されるパラメタ

link

javadoc出力に対して、指定したURLでリンクします。 これは、linkとlinkoffline属性と同じ役目を果たします。 どちらかの (または、同時に両方の) 記法を使用できますが、 ネストした要素の方が、簡単に複数の引数を指定することができます。

パラメタ

属性 説明 必須
href リンクしたい外部のドキュメントのURL。 はい
offline ドキュメント生成時に、このリンクがオンラインで利用できない場合にtrueを指定します。 いいえ
packagelistLoc 外部のドキュメントのパッケージリストファイルを含むディレクトリの場所。 オフライン属性がtrueの場合のみ。

groups

概要ページのそれぞれのパッケージを、指定したグループに、一グループが一つのテーブルになるように分割します。 これは、group属性と同じ役目を果たします。 どちらかの記法(または同時に両方)を使用することができますが、ネストした要素の方が複数の引数を簡単に指定することができます。

属性 説明 必須
title このグループの題名。 はい
packages このグループに含まれるパッケージのリスト。 はい

doclet

ネストした要素のdocletは、javadocが入力ソースファイルを処理するために使用するdocletを指定するために使用します。 多くの標準のjavadoc引数は、実際には標準docletの引数です。 javadocタスクの属性を指定する場合には、ネストした要素<doclet>で指定されたdocletに渡されます。 だから、使用したdocletが解釈できる場合にだけ、そのような属性を指定すべきです。

docletが追加パラメタを必要とする場合には、 <doclet>要素内の<param>要素で指定することができます。 これらのパラメタは、簡単な文字列に制限されます。 doclet要素の使用例を、次に示します。

  <javadoc ...>
     <doclet name="theDoclet"
             path="path/to/theDoclet">
        <param name="-foo" value="foovalue"/>
        <param name="-bar" value="barvalue"/>
     </doclet>
  </javadoc>

sourcepath, classpathとbootclasspath

Javadocsourcepath, classpathbootclasspath属性は、PATH類似構造であり、それぞれネストしたsourcepath, classpathbootclasspath要素で設定することができます。

  <javadoc packagenames="com.dummy.test.*"
           sourcepath="src"
           destdir="docs/api"
           author="true"
           version="true"
           use="true"
           windowtitle="Test API"
           doctitle="<h1>Test</h1>"
           bottom="<i>Copyright &#169; 2000 Dummy Corp. All Rights Reserved.</i>">
    <group title="Group 1 Packages" packages="com.dummy.test.a*"/>
    <group title="Group 2 Packages" packages="com.dummy.test.b*"/>
    <link offline="true" href="http://java.sun.com/products/jdk/1.2/docs/api/" packagelistLoc="C:\tmp"/>
    <link href="http://developer.java.sun.com/developer/products/xml/docs/api/"/>
  </javadoc>

Copyright (C) 2000,2001 Apache Software Foundation. All rights Reserved.

[訳注:これはXXXXが翻訳しました。日本語訳に対するコメントがあれば report@jajakarta.orgに送ってください]