生成文檔

文檔在任何項(xiàng)目中都是必須的。文檔對(duì)一個(gè)項(xiàng)目的維護(hù)起了至關(guān)重要的作用。 通過使用內(nèi)置的 Javadoc 工具，使用 Java 生成文檔變得更加容易。Ant 通過按需生成文檔使得這個(gè)步驟甚至變得更簡(jiǎn)單。

如你所知，javadoc 工具具有高度的靈活性，而且其還允許進(jìn)行一些配置。Ant 通過使用 javadoc 任務(wù)的方式來公開這些配置選項(xiàng)。如果你對(duì) javadoc 不熟悉的話，我們建議你先看一下 Java 文檔教程。

下述的章節(jié)列出了在 Ant 中最常使用的 javadoc 的選項(xiàng)。

屬性

源包括源路徑，源路徑引用或者源文件三個(gè)屬性。

• 源路徑 (sourcepath) 指向源文件所在的文件夾，例如： src 文件夾。
• 源路徑引用 (sourcepathref) 指向由該路徑屬性引用的路徑，例如：delegates.src.dir 。
• 源文件 (sourcefiles) 在你想指定單獨(dú)的文件時(shí)使用，比如指定一個(gè)逗號(hào)分隔列表。

目標(biāo)路徑是通過使用 destdir 文件夾來指定的，例如 build.dir 。

你能夠通過指定應(yīng)被包括的包的名字來過濾 javadoc 任務(wù)。這可以通過使用 packagenames 屬性實(shí)現(xiàn)，即一個(gè)以逗號(hào)分隔的包文件列表。

你可以過濾 javadoc 過程以只顯示公有的，私有的，包或者被保護(hù)的類和成員。這些可以通過使用 private，public，package 和 protected 屬性實(shí)現(xiàn)。

你也可以通過使用相應(yīng)的屬性來告訴 javadoc 任務(wù)去包含作者和版本信息。

你也可以使用 group 屬性將所有的包組織在一起，以使得他們更易被操作。

將上述內(nèi)容集中到一起

讓我們繼續(xù)我們的主題，Hello world 傳真應(yīng)用程序。讓我們給我們的傳真應(yīng)用項(xiàng)目添加一個(gè)文檔目標(biāo)。

下面給出的例子是我們?cè)陧?xiàng)目中使用的 javadoc 任務(wù)。在這個(gè)例子中，我們指定 javadoc 去使用 src.dir 作為源目錄，doc 作為目標(biāo)。

我們還定制窗口標(biāo)題，標(biāo)題，以及顯示在 java 文檔頁(yè)上的頁(yè)腳信息。

此外，我們還創(chuàng)建了三個(gè)組：

• 為源文件夾中的實(shí)用工具類創(chuàng)建了一個(gè)組。
• 為用戶接口的類創(chuàng)建了一個(gè)組。
• 為數(shù)據(jù)庫(kù)相關(guān)的類創(chuàng)建了一個(gè)組。

您可能會(huì)注意到，數(shù)據(jù)包組含有兩個(gè)包 -- 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>

讓我們運(yùn)行 javadoc Ant 任務(wù)。它將生成 java 文檔文件，并將這些文件放置于 doc 文件夾中。

當(dāng)執(zhí)行 javadoc 目標(biāo)時(shí)，其產(chǎn)生以下的輸出：

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

>java doc has been generated!

>BUILD SUCCESSFUL
>Total time: 10.63 second

java 文檔文件現(xiàn)在出現(xiàn)在 doc 文件夾中。

通常情況下，javadoc 文件作為發(fā)行版或者包目標(biāo)的一部分。