Javadoc/Javadoc2

已棄用：javadoc2 任務僅指向 javadoc 任務，且其存在是為了向後相容性考量。由於此任務將在未來版本中移除，強烈建議改用 javadoc。

說明

使用 javadoc 工具產生程式碼文件。

來源目錄將會遞迴掃描 Java 來源檔案以進行處理，但僅會將符合包含規則且不符合排除規則的檔案傳遞給 javadoc 工具。這允許使用萬用字元在封裝名稱之間進行選擇，以減少冗長度並降低管理成本。然而，此任務與 javac 任務不同，沒有「已變更」檔案的概念。這表示每次執行此任務時，所有封裝都會被處理。不過，通常會較不頻繁地使用此任務。

注意：由於 javadoc 會呼叫 System.exit()，因此無法在與 Apache Ant 相同的 JVM 中執行 javadoc，否則會損壞功能。因此，此任務總是會分岔 JVM。此開銷並不顯著，因為 javadoc 通常是一個大型應用程式，且呼叫頻率很低。

注意：packagelist 屬性允許您在 Ant 檔案外指定要記錄的封裝清單。建議將所有內容都包含在 build.xml 檔案中。新增此選項是為了讓從一般 makefile（您會在此使用 javadoc 的此選項）移轉變得更容易。packagelist 中所列的封裝並未經過檢查，因此即使某些封裝遺失或損毀，任務仍會執行。如果您想從現有的 makefile 轉換，請使用此選項。一旦執行順利，您應該改用一般表示法。

注意：在為包含註解的類別產生 JavaDoc 時，您可能會收到 java.lang.ClassCastException: com.sun.tools.javadoc.ClassDocImpl。這是因為 錯誤 6442982。原因是 javadoc 找不到已使用註解的實作。解決方法是使用 classpath、classpathref 屬性或巢狀 <classpath> 元素，將包含這些實作的 jar（例如 JAXBs @XmlType，...）提供給 <javadoc>。

注意：執行 javadoc 時會發生許多問題，源自於命令列過長，即使錯誤訊息沒有提供任何提示，這也可能是問題。如果您在執行任務時遇到問題，請先嘗試將 useexternalfile 屬性設定為 true。

如果您使用多種方式來指定 javadoc 應該在哪裡尋找原始碼，您的結果將會是所有指定文件檔的聯集。例如，如果您指定一個 sourcepath 屬性，還有一個嵌套的 packageset，兩個都指向同一個目錄，您的 excludepackagenames 屬性將不會有任何作用，除非它與 packageset 的 exclude 模式一致（反之亦然）。

參數

group 屬性的格式

參數以逗號分隔。每個單一參數是 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 給出的清單中的其中一項相同。

參數

excludepackage

與 excludepackagenames 給出的清單中的其中一項相同。

參數

module

自 Ant 1.10.6 起

與 modulenames 給出的清單中的其中一項相同。

參數

來源

與 sourcefiles 給出的清單中的其中一項相同。

參數

doctitle

與 doctitle 屬性相同，但您可以使用這種方式將文字巢狀在元素內。

如果巢狀文字包含換行符，您必須使用 useexternalfile 屬性，並將其設定為 true。

header

類似於 <doctitle>。

footer

類似於 <doctitle>。

底部

類似於 <doctitle>。

連結

在指定的 URL 建立連結到 javadoc 輸出。這會執行與 link 和 linkoffline 屬性相同的作用。您可以使用任一語法（或同時使用），但使用巢狀元素，您可以輕鬆指定參數的多個執行個體。

參數

群組

將概觀頁面上的套件分隔成您指定的群組，每個表格一個群組。這與 group 屬性扮演相同角色。您可以使用任一種語法（或同時使用兩種語法），但透過巢狀元素，您可以輕鬆指定參數的多個執行個體。

參數

標題可以指定為包含文字內容的巢狀 <title> 元素，而套件可以列在巢狀 <package> 元素中，就像主工作一樣。

文件說明

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 元素指定標準標籤，因為您想要決定標籤的輸出順序，則不能設定這些標籤的 description 屬性。

參數

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

標籤

標籤巢狀元素用於指定自訂 標籤，超出 預設標籤。

參數

來源路徑、類別路徑、開機類別路徑、模組路徑、模組來源路徑

Javadoc 的 來源路徑、類別路徑、開機類別路徑、模組路徑 和 模組來源路徑 屬性是 類似 PATH 的結構，也可以分別透過巢狀 來源路徑、類別路徑、開機類別路徑、模組路徑 和 模組來源路徑 元素設定。

引數

自 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>