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を使用することを強く勧めます。

下のテーブル内で、1.1の意味はJava VMが1.1ならば利用可能で、 1.2はバージョン1.2又は1.3、そして、1.4+は少なくともVMのバージョン1.4、1.2+の意味は少なくともVMのバージョン1.2.

パラメータ

属性 説明 利用可能環境 必須
sourcepath ソースファイルを探す場所を指定します。 all 少なくとも3つのうち一つか、ネストした<sourcepath><fileset>または<packageset>
sourcepathref ソースファイルを探す場所を任意の場所で定義されたPATHに対する参照を用いて指定します。 all
sourcefiles カンマで区切られたソースファイルの一覧。 -- ネストしたsource要素を参照してください。 all
destdir ファイルの出力先ディレクトリ。 all Yes
maxmemory javadocを実行するVMに割り当てる最大メモリ量。 all No
packagenames (ワイルドカードで終了する) パッケージファイルのコンマで区切られたリスト。 -- ネストしたpackage要素を参照してください。 all No
packageList 処理するパッケージを含むファイル名。 all No
classpath ユーザのクラスファイルを探す場所の指定。 all No
Bootclasspath ブートストラップクラスローダがロードするクラスファイルの場所をオーバライドします。 1.2 No
classpathref 任意の場所で指定された参照によって、ユーザのクラスファイルを探す場所を指定します。 all No
bootclasspathref 任意の場所で定義したPATHに対する参照によって、ブートストラップクラスローダがロードするクラスファイルの場所をオーバライドします。 1.2 No
Extdirs インストールした拡張の場所をオーバライドします。 1.2 No
Overview HTMLファイルから概要ドキュメントを読み込みます。 1.2 No
access アクセス・モード: publicprotectedpackage、またはprivateのどれか all No (デフォルトは、 protected)
Public publicクラスとメンバのみを表示します。 all No
Protected protected/publicクラスとメンバを表示します (デフォルト) all No
Package package/protected/publicクラスとメンバを表示します。 all No
Private すべてのクラスとメンバを表示します。Show all classes and members all No
Old JDK 1.1をエミュレートするdocletを使用して出力を生成します。 1.2 No
Verbose Javadocの動作状況についてのメッセージを出力します。 1.2 No
Locale 使用するロケール。例、en_US や en_US_WIN 1.2 No
Encoding ソースファイルエンコーディング名。 all No
Version @versionパラグラフを含めます。 all No
Use クラスとパッケージの使用方法のページを作成します。 1.2 No
Author @authorパラグラフを含めます。 all No
Splitindex 索引を一文字に対して一つのファイルに分割します。 1.2 No
Windowtitle ドキュメントのブラウザのウィンドウの題名。(テキスト) 1.2 No
Doctitle パッケージの索引の(最初の)ページに題名を含めます (HTMLコード) 1.2 No
Header 各ページにヘッダのテキストを含めます。(HTMLコード) 1.2 No
Footer 各ページにフッタのテキストを含めます。(HTMLコード) 1.2 No
bottom 各ページの下部にテキストを含めます。(HTMLコード) 1.2 No
link 指定されたURLでjavadoc出力にリンクを作成します。 -- ネストしたlink要素を参照してください。 1.2+ No
linkoffline <url2>にあるパッケージリストを用いて、<URL>のdocsにリンクを作成します。 -- ネストしたlink要素を参照してください。 1.2+ No
group 指定したパッケージを概要ページで一緒にグループ化します。 フォーマットは下で説明しています。 -- ネストしたgroup要素を参照してください。 1.2+ No
nodeprecated @deprecated情報を含めません。 all No
nodeprecatedlist 推奨されないリストを生成しません。 1.2+ No
notree クラス階層を生成しません。 all No
noindex 索引を生成しません。 all No
nohelp ヘルプのリンクを生成しません。 1.2+ No
nonavbar ナビゲーションバーを生成しません。 1.2+ No
serialwarn @serialタグについての警告を生成します。 1.2+ No
helpfile 使用するHTMLのヘルプファイルを指定します。 1.2+ No
stylesheetfile 使用するCSSスタイルシートを指定します。 1.2+ No
charset 生成したドキュメントをクロスプラットフォームで閲覧するための文字セット。 1.2+ No
docencoding 出力ファイルのエンコーディング名。 all No
doclet ドキュメントを生成するために使用するdocletを起動するクラスファイルを指定します。 -- ネストしたdoclet要素を参照してください。 1.2+ No
docletpath -docletオプションと一緒に指定するdocletクラスファイルへのパスを指定します。 1.2+ No
docletpathref 任意の場所で定義されたPATHに対する参照によって、 -docletオプションと一緒に指定するdocletクラスファイルへのパスを指定します。 1.2+ No
additionalparam javadocコマンドラインに追加するパラメタを追加します。 docletsにとって便利です。 スペースを含んでいるパラメータは、&quot;を使って引用する必要があります。 ネストしたarg要素を参照してください。 all No
failonerror コマンドが0以外の返り値で終了した場合には、ビルドプロセスを停止します。 all No
excludepackagenames カンマで区切られた、ドキュメントを作成したくないパッケージのリスト。 -- ネストしたexcludepackage要素を参照してください。 all No
defaultexcludes デフォルトの除外を使うかどうか(yes | no)。省略時は、デフォルトの除外は使われる。 all No
useexternalfile srcfiles、あるいはネストしたsource要素で指定されたソースファイル名が、 コマンドラインを短縮するために一時ファイルに書き込まれるかどうかを示す。 これはまた、packagenames属性あるいはネストしたパッケージ要素により指定されたパッケージ名についても適用される。 (yes | no). デフォルトはno。 1.2+ No
source J2SE バージョン1.4のソースコードに存在するアサーションを、javadocに処理させる必要があるかどうかを指定する。 "javac -source 1.4"としてコンパイルする必要があるソースコード(つまり、アサーションを含むソース)を文書化する場合、この値を"1.4"とする必要がある。 [訳注:javadoc 1.4の新機能を参照]
カスタムDocletを使った場合には無視される。
1.4+ No
linksource ソースファイルへのリンクを生成します。 Ant 1.6から (yes | no) デフォルトは、no 1.4+ No
breakiterator 新しいbreakiteratorアルゴリズムを使用します。 Ant 1.6から (yes | no)デフォルトは、no 1.4+ No
noqualifier -noqualifier引数を有効にします。 - all又は、コロン区切りのパッケージリストでなければいけません。 Ant 1.6から 1.4+ No

グループ属性のフォーマット

引数はカンマ区切りです。 それぞれの単一引数は、2つのスペースで区切られています。 最初のは、グループのタイトルで、次のは、コロン区切りのパッケージのリストです。

もし、もっとグループを指定したり、タイトルにカンマやスペース文字を含めたかったら、 ネストしたグループ要素の使用をお勧めします。

例えば、

    group="XSLT_Packages org.apache.xalan.xslt*,XPath_Packages org.apache.xalan.xpath*"

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

packageset

DirSetです。 すべてのマッチした、Javaのソースファイルを含むディレクトリは、 パッケージ名として、javadocに渡されます。 パッケージ名は、ドット区切りのディレクトリ名として翻訳し、生成されます。 Antは、packagesetのベースディレクトリがパッケージ階層のルートを指すと仮定します。

タスクのpackagenames, excludepackagenames,defaultexcludes属性は、 ネストした<packageset>要素に影響しません。

fileset

FileSetです。 すべてのマッチしたファイルは、ソースファイルとして、javadocに渡されます。 Antは、**/*.javaパターンを含むものを、ファイルセットに自動的に追加します。

ネストしたファイルセットは、デフォルトパッケージのドキュメントソースとしてか、 ドキュメントからファイルを除外したい場合に使用することができます。 もし、すべてのソースを保存したくて、デフォルトパッケージを使わなければ、 javadocsのパフォーマンスが増すので、packagesetsを代わりに使うべきです。

タスクのpackagenames, excludepackagenames,defaultexcludes属性は、 ネストした<fileset>要素に影響しません。

package

packagenamesのリスト内でひとつだけのエントリのときと同じ

パラメータ
属性 説明 必須
name パッケージ名 (おそらくワイルドカード) Yes

excludepackage

excludepackagenamesのリスト内でひとつだけのエントリのときと同じ

パラメータ
packageと同じ

source

sourcefilesのリスト内でひとつだけのエントリのときと同じ

パラメータ
属性 説明 必須
file ドキュメントのためのソースファイル Yes

doctitle

doctitle属性と同じだが、この方法で要素内のテキストをネストすることができる。

header

<doctitle>と類似

footer

<doctitle>と類似

bottom

<doctitle>と類似

link

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

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

group

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

パラメータ
属性 説明 必須
title グループのタイトル Yes。ネストした<title>が無いことを前提として。
packages グループを含んだパッケージのリスト。 複数のパッケージは、':'区切りになります。 Yes。 ネストした<package>が無いことを前提として。

おそらくタイトルは、ネストした<title>要素のテキスト内容によって示され、 おそらくパッケージは、mainタスクのような、ネストした<package>要素でリストされます。

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>

tag

ネストしたtag要素は、カスタムタグの指定として使われます。 このオプションは、Java 1.4.でのみ利用可能です。

もし、タグが出力する順序を決めたくて、ネストしたタグ要素を使用し、標準のタグを指定したければ、 これらのタグにdescription属性を設定してはいけません。

パラメータ
属性 説明 必須
name タグの名前 (todoなど) Yes。dir属性が指定されない限り。
description タグの説明(To do:)など Yes。 dir属性が指定されないか、タグの名前が標準のタグ
enabled タグが可能かどうか (デフォルトは、true) No
scope タグのスコープ - 要素で使えます。これは、いくつかの要素で、 カンマ区切りのリストです:overview, packages, types, constructors, methods, fields 又はデフォルト, all No
dir もしこの属性が指定されたら、この要素は暗黙的に、 filesetとして機能します。 このファイルセットで含んでいるファイルは、 javadocリファレンスガイドで説明されているように、 行区切りで、それぞれのタグ定義をするべきです。

ejb.bean:t:"XDoclet EJB Tag"
todo:a:"To Do"

注意: もし、この属性が指定されたならば、この要素内のすべてのほかの属性は無視されます。
No

taglet

ネストしたtaglet要素は、カスタムタグレットの指定として使われます。 このオプションは、Java 1.4.でのみ利用可能です。

パラメータ
属性 説明 必須
name タグレットクラスの名前 (com.sun.tools.doclets.ToDoTagletなど) Yes
path タグレットクラスの検索パスを指定します。 (/home/tagletsなど) このパスは、おそらくネストした<path>要素で示されます。 No

sourcepath, classpathとbootclasspath

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

arg

引数の追加を示すために、ネストした<arg>を使います。 コマンドライン引数を参照してください。 Ant 1.6から

  <javadoc packagenames="com.dummy.test.*"
           sourcepath="src"
           excludepackagenames="com.dummy.test.doc-files.*"
           defaultexcludes="yes"
           destdir="docs/api"
           author="true"
           version="true"
           use="true"
           windowtitle="Test API">
    <doctitle><![CDATA[<h1>Test</h1>]]></doctitle>
    <bottom><![CDATA[<i>Copyright &#169; 2000 Dummy Corp. All Rights Reserved.</i>]]></bottom>
    <tag name="todo" scope="all" description="To do:" />
    <group title="Group 1 Packages" packages="com.dummy.test.a*"/>
    <group title="Group 2 Packages" packages="com.dummy.test.b*:com.dummy.test.c*"/>
    <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>

同じように

  <javadoc
           destdir="docs/api"
           author="true"
           version="true"
           use="true"
           windowtitle="Test API">

    <packageset dir="src" defaultexcludes="yes">
      <include name="com/dummy/test/**" />
      <exclude name="com/dummy/test/doc-files/**"/>
    </packageset>

    <doctitle><![CDATA[<h1>Test</h1>]]></doctitle>
    <bottom><![CDATA[<i>Copyright &#169; 2000 Dummy Corp. All Rights Reserved.</i>]]></bottom>
    <tag name="todo" scope="all" description="To do:" />
    <group title="Group 1 Packages" packages="com.dummy.test.a*"/>
    <group title="Group 2 Packages" packages="com.dummy.test.b*:com.dummy.test.c*"/>
    <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>

又は

  <javadoc
           destdir="docs/api"
           author="true"
           version="true"
           use="true"
           windowtitle="Test API">

    <fileset dir="src" defaultexcludes="yes">
      <include name="com/dummy/test/**" />
      <exclude name="com/dummy/test/doc-files/**"/>
    </fileset>

    <doctitle><![CDATA[<h1>Test</h1>]]></doctitle>
    <bottom><![CDATA[<i>Copyright &#169; 2000 Dummy Corp. All Rights Reserved.</i>]]></bottom>
    <tag name="todo" scope="all" description="To do:" />
    <group title="Group 1 Packages" packages="com.dummy.test.a*"/>
    <group title="Group 2 Packages" packages="com.dummy.test.b*:com.dummy.test.c*"/>
    <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 © 2000-2004 The Apache Software Foundation. All rights Reserved.

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