Ant 简明教程

Ant - Build Documentation

文档在任何项目中都是必不可少的。文档在项目的维护中发挥了重要作用。Java 通过使用内置 javadoc 工具简化了文档的编写。Ant 通过按需生成文档，进一步简化了这一过程。

众所周知，javadoc 工具非常灵活，并允许使用许多配置选项。Ant 通过 javadoc 任务公开这些配置选项。如果您不熟悉 javadoc，建议您从这篇 Java 文档教程开始学习。

以下部分列出了 Ant 中使用的一些最常见的 javadoc 选项。

Attributes

源可以通过 sourcepath 、 sourcepathref 或 sourcefiles 指定。

  1. sourcepath 用于指向源文件所在的文件夹（例如 src 文件夹）。

  2. sourcepathref 用于引用 path 属性引用的路径（例如，delegates.src.dir）。

  3. 当您希望将各个文件指定为逗号分隔的列表时，请使用 sourcefiles 。

目标路径是使用 destdir 文件夹指定的（例如 build.dir）。

您可以通过指定要包含的程序包名称来过滤 javadoc 任务。这是通过使用 packagenames 属性（逗号分隔的程序包文件列表）来实现的。

您可以过滤 javadoc 进程，以仅显示 public、private、package 或 protected 类和成员。这是通过使用 private 、 public 、 package 和 protected 属性实现的。

您还可以通过使用相应属性来告诉 javadoc 任务包含作者和版本信息。

您还可以使用 group 属性对包进行分组，以便于导航。

Putting it all together

让我们继续 Hello world 传真应用程序的主题，并向传真应用程序项目添加文档目标。

下面给出了项目中使用的一个 javadoc 任务示例。在此示例中，我们指定 javadoc 使用 src.dir 作为源目录，使用 doc 作为目标。

我们还自定义了显示在 java 文档页面上的窗口标题、页眉和页脚信息。

此外，我们还创建了三个组：

  1. 第一个组是我们源文件夹中的实用程序类，

  2. 一个用于用户界面类，

  3. 一个用于数据库相关类。

你可能会注意到，data 包组有两个包——faxapp.entity 和 faxapp.dao。

<target name="generate-javadoc">
   <javadoc packagenames="faxapp.*" sourcepath="${src.dir}"
      destdir="doc" version="true" windowtitle="Fax Application">
      <doctitle><![CDATA[= Fax Application =]]></doctitle>
      <bottom>
         <![CDATA[Copyright © 2011. All Rights Reserved.]]>
      </bottom>
      <group title="util packages" packages="faxapp.util.*"/>
      <group title="web packages" packages="faxapp.web.*"/>
      <group title="data packages" packages="faxapp.entity.*:faxapp.dao.*"/>
   </javadoc>
   <echo message="java doc has been generated!" />
</target>

让我们执行 javadoc Ant 任务。它会在 doc 文件夹中生成并放置 java 文档文件。

当 javadoc target 执行时，它会生成以下结果 −

C:\>ant generate-javadoc
Buildfile: C:\build.xml

java doc has been generated!

BUILD SUCCESSFUL
Total time: 10.63 second

java 文档文件现在存在于 doc 文件夹中。

通常，javadoc 文件在发行或包目标中生成。