Javadoc/Javadoc2

非推奨: javadoc2タスクは単にjavadocタスクを指すだけであり、後方互換性のために存在しています。このタスクは将来のバージョンで削除される予定ですので、代わりにjavadocを使用することを強くお勧めします。

説明

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

ソースディレクトリは、処理対象となるJavaソースファイルを探して再帰的にスキャンされますが、インクルールールに一致し、除外ルールに一致しないもののみがjavadocツールに渡されます。これにより、ワイルドカードを使用してパッケージ名を選択できるため、冗長さを減らし、時間の経過に伴う管理コストを削減できます。ただし、このタスクにはjavacタスクとは異なり、「変更された」ファイルの概念はありません。つまり、このタスクが実行されるたびにすべてのパッケージが処理されます。ただし、一般的に、このタスクの使用頻度ははるかに低いです。

注:javadocはSystem.exit()を呼び出すため、機能を壊さずにApache Antと同じJVM内でjavadocを実行することはできません。このため、このタスクは常にJVMをフォークします。javadocは通常、負荷の高いアプリケーションであり、呼び出される頻度が少ないため、このオーバーヘッドはそれほど大きくありません。

注:packagelist属性を使用すると、Antファイルの外でドキュメント化するパッケージのリストを指定できます。すべてのものをbuild.xmlファイル内に含める方がはるかに良い方法です。このオプションは、javadocのこのオプションを使用する通常のMakefileからの移行を容易にするために追加されました。packagelistにリストされているパッケージはチェックされないため、一部のパッケージが欠落または破損していてもタスクは実行されます。既存のMakefileから変換する場合は、このオプションを使用してください。実行が開始されたら、通常の表記法に切り替える必要があります。

注:アノテーションを含むクラスのJavaDocsを生成するときに、java.lang.ClassCastException: com.sun.tools.javadoc.ClassDocImplが発生する場合があります。これはバグ6442982が原因です。原因は、javadocが使用されているアノテーションの実装を見つけられないことです。回避策は、JAXBの@XmlTypeなどの実装を含むJARを、classpath、classpathref属性、またはネストされた<classpath>要素を使用して<javadoc>に提供することです。

注:javadocの実行に関する多くの問題は、コマンドラインが長くなりすぎたことに起因します。エラーメッセージにはこれが問題であるというヒントはまったくありませんが。タスクで問題が発生した場合は、最初にuseexternalfile属性をtrueに設定してみてください。

javadocがソースを検索する場所を指定する方法を複数使用すると、結果は指定されたすべてのドキュメントの結合になります。たとえば、sourcepath属性と、同じディレクトリを指すネストされたpackagesetの両方を指定した場合、excludepackagenames属性は、packagesetのexcludeパターンと一致しない限り効果がありません（逆もまた同様）。

パラメーター

group属性の形式

引数はカンマ区切りです。各単一の引数は2つのスペース区切りの文字列で、最初の文字列はグループのタイトルであり、2番目の文字列はコロン区切りのパッケージリストです。

複数のグループ、またはタイトルにカンマやスペース文字が含まれているグループを指定する必要がある場合は、ネストされたgroup要素を使用することを強くお勧めします。

例:

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（およびincludenosourcepackagesがtrueの場合は**/package.html）を自動的に追加します。

ネストされたファイルセットは、デフォルトパッケージにあるソースをドキュメント化したり、特定のファイルをドキュメントから除外したりする場合に使用できます。すべてのソースファイルをドキュメント化し、デフォルトパッケージを使用しない場合は、代わりにpackagesetを使用する必要があります。これにより、javadocのパフォーマンスが向上します。

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

sourcefiles

任意のファイルシステムベースのリソースコレクションのコンテナです。ネストされたコレクション（ネストされたファイルセット、ファイルリスト、またはパスを含む）に含まれるすべてのファイルが、ソースファイルとしてjavadocに渡されます。

package

packagenamesで指定されたリストの1つのエントリと同じです。

パラメーター

excludepackage

excludepackagenamesで指定されたリストの1つのエントリと同じです。

パラメーター

module

Ant 1.10.6以降

modulenamesで指定されたリストの1つのエントリと同じです。

パラメーター

source

sourcefilesで指定されたリストの1つのエントリと同じです。

パラメーター

doctitle

doctitle属性と同じですが、このように要素内にテキストをネストできます。

ネストされたテキストに改行が含まれている場合は、useexternalfile属性を使用し、trueに設定する必要があります。

header

<doctitle>と同様です。

footer

<doctitle>と同様です。

bottom

<doctitle>と同様です。

link

指定されたURLでjavadoc出力へのリンクを作成します。これは、linkおよびlinkoffline属性と同じ役割を果たします。どちらの構文（または両方を同時に）使用できますが、ネストされた要素を使用すると、引数の複数の出現を簡単に指定できます。

パラメーター

group

指定したグループごとに1つのテーブルで、概要ページのパッケージを区切ります。これは、group属性と同じ役割を果たします。どちらの構文（または両方を同時に）使用できますが、ネストされた要素を使用すると、引数の複数の出現を簡単に指定できます。

パラメーター

タイトルは、テキストコンテンツを持つネストされた<title>要素として指定でき、パッケージはメインタスクと同様にネストされた<package>要素でリストできます。

doclet

docletネスト要素は、javadocが入力ソースファイルを処理するために使用するドックレットを指定するために使用されます。標準のjavadoc引数の多くは、実際には標準ドックレットの引数です。これらがjavadocタスクの属性で指定されている場合、<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要素を使用して標準タグを指定する場合は、これらのタグにdescription属性を設定しないでください。

パラメーター

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

taglet

tagletネスト要素は、デフォルトのタグレット以外のカスタムタグレットを指定するために使用されます。

パラメーター

sourcepath、classpath、bootclasspath、modulepath、modulesourcepath

Javadocのsourcepath、classpath、bootclasspath、modulepath、およびmodulesourcepath属性は、PATHのような構造であり、ネストされたsourcepath、classpath、bootclasspath、modulepath、およびmodulesourcepath要素をそれぞれ介して設定することもできます。

arg

Ant 1.6以降

ネストされた<arg>を使用して、追加の引数を指定します。コマンドライン引数を参照してください。

例

<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="https://docs.oracle.com/javase/8/docs/api/" packagelistLoc="C:\tmp"/>
  <link href="https://docs.oracle.com/javase/8/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="https://docs.oracle.com/javase/8/docs/api/" packagelistLoc="C:\tmp"/>
  <link href="https://docs.oracle.com/javase/8/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="https://docs.oracle.com/javase/8/docs/api/" packagelistLoc="C:\tmp"/>
  <link href="https://docs.oracle.com/javase/8/docs/api/"/>
</javadoc>