Javadoc/Javadoc2

弃用: javadoc2 任务只是指向 javadoc 任务，它是为了向后兼容而存在的。由于此任务将在未来版本中删除，强烈建议您使用 javadoc 代替。

描述

使用 javadoc 工具生成代码文档。

源代码目录将被递归扫描以查找要处理的 Java 源代码文件，但只有那些匹配包含规则且不匹配排除规则的文件才会传递给 javadoc 工具。这允许使用通配符在包名称之间进行选择，从而减少冗长并降低随着时间的推移而产生的管理成本。但是，此任务不像 javac 任务那样具有“已更改”文件的概念。这意味着每次运行此任务时都会处理所有包。但是，通常情况下，此任务的使用频率要低得多。

注意: 由于 javadoc 调用 System.exit()，因此 javadoc 无法在与 Apache Ant 相同的 JVM 中运行，否则会破坏功能。出于这个原因，此任务始终会派生 JVM。由于 javadoc 通常是一个重量级应用程序，并且调用频率很低，因此这种开销并不重要。

注意: packagelist 属性允许您在 Ant 文件之外指定要记录的包列表。将所有内容包含在 build.xml 文件中是一个更好的做法。添加此选项是为了更容易地从常规 makefile 迁移，您将在其中使用此选项的 javadoc。在 packagelist 中列出的包不会被检查，因此即使某些包丢失或损坏，任务也会执行。如果您希望从现有的 makefile 转换，请使用此选项。一旦一切正常运行，您应该切换到常规表示法。

注意: 当为包含注释的类生成 JavaDocs 时，您可能会收到 java.lang.ClassCastException: com.sun.tools.javadoc.ClassDocImpl。这是由于 bug 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 给出的列表中的一个条目相同。

参数

source

与 sourcefiles 给出的列表中的一个条目相同。

参数

doctitle

与 doctitle 属性相同，但您可以通过这种方式在元素内嵌套文本。

如果嵌套文本包含换行符，则必须使用 useexternalfile 属性并将其设置为 true。

header

类似于 <doctitle>。

footer

类似于 <doctitle>。

bottom

类似于 <doctitle>。

link

在给定 URL 处创建指向 javadoc 输出的链接。这与 link 和 linkoffline 属性的作用相同。您可以使用任一语法（或同时使用两者），但使用嵌套元素，您可以轻松地指定参数的多个出现。

参数

group

将概述页面上的包分隔成您指定的任何组，每个组一个表。这与 group 属性的作用相同。您可以使用任一语法（或同时使用两者），但使用嵌套元素，您可以轻松地指定参数的多个出现。

参数

标题可以指定为具有文本内容的嵌套 <title> 元素，并且包可以列出为嵌套的 <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 元素指定标准标签，因为您想确定标签的输出顺序，则不能为这些标签设置 description 属性。

参数

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

taglet

taglet 嵌套元素用于指定除 默认 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>