构建文档（ Build Documentation）

优质

小牛编辑

128浏览

2023-12-01

文档是任何项目的必需品。文档在维护项目中起着重要作用。 Java通过使用内置的javadoc工具使文档更容易。通过按需生成文档，Ant使其变得更加容易。

如您所知，javadoc工具非常灵活，允许许多配置选项。 Ant通过javadoc任务公开这些配置选项。如果您不熟悉javadoc，我们建议您从本Java Documentation Tutorial开始。

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

属性 (Attributes)

可以使用sourcepath ， sourcepathref或sourcefiles指定Source。

sourcepath用于指向源文件的文件夹（例如src文件夹）。
sourcepathref用于引用path属性引用的路径（例如，delegates.src.dir）。
如果要将各个文件指定为逗号分隔列表，则使用sourcefiles 。

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

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

您可以过滤javadoc进程以仅显示公共，私有，包或受保护的类和成员。这是通过使用private ， public ， package和protected属性实现的。

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

您还可以使用group属性将包分组在一起，以便轻松导航。

把它们放在一起

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

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

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

此外，我们创建了三个组 -

一个用于源文件夹中的实用程序类，
一个用于用户界面类，和
一个用于数据库相关的类。

您可能会注意到数据包组有两个包 - 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任务。它生成并将java文档文件放在doc文件夹中。

当执行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文件是作为发布或包目标的一部分生成的。