Ant 简明教程

Ant - Build Documentation

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

Documentation is a must in any project. Documentation plays a great role in the maintenance of a project. Java makes documentation easier by the use of the inbuilt javadoc tool. Ant makes it even easier by generating the documentation on demand.

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

As you know, the javadoc tool is highly flexible and allows a number of configuration options. Ant exposes these configuration options via the javadoc task. If you are unfamiliar with javadocs, we suggest that you start with this Java Documentation Tutorial.

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

The following section lists the most commonly used javadoc options that are used in Ant.

Attributes

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

Source can be specified using sourcepath, sourcepathref or sourcefiles.

  1. sourcepath is used to point to the folder of the source files (e.g. src folder).

  2. sourcepathref is used to refer a path that is referenced by the path attribute (e.g, delegates.src.dir).

  3. sourcefiles is used when you want to specify the individual files as a comma separated list.

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

Destination path is specified using the destdir folder (e.g build.dir).

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

You could filter the javadoc task by specifying the package names which are to be included. This is achieved by using the packagenames attribute, a comma separated list of package files.

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

You could filter the javadoc process to show only the public, private, package, or protected classes and members. This is achieved by using the private, public, package and protected attributes.

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

You could also tell the javadoc task to include the author and version information by using the respective attributes.

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

You could also group the packages together using the group attribute, so that it becomes easy to navigate.

Putting it all together

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

Let us continue our theme of the Hello world Fax application and add a documentation target to our Fax application project.

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

Given below is an example javadoc task used in our project. In this example, we have specified the javadoc to use the src.dir as the source directory, and doc as the target.

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

We have also customised the window title, the header, and the footer information that appear on the java documentation pages.

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

Also, we have created three groups −

  1. one for the utility classes in our source folder,

  2. one for the user interfaces classes, and

  3. one for the database related classes.

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

You may notice that the data package group has two packages -– faxapp.entity and 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 文档文件。

Let us execute the javadoc Ant task. It generates and places the java documentation files in the doc folder.

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

When the javadoc target is executed, it produces the following outcome −

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

java doc has been generated!

BUILD SUCCESSFUL
Total time: 10.63 second

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

The java documentation files are now present in the doc folder.

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

Typically, the javadoc files are generated as a part of the release or package targets.