1.8 生成Java文檔

Java程序員在使用JDK開發時，最好的幫助信息來自Sun公司發布的Java文檔。Java API文檔分包、分類地詳細提供了各方法、屬性的幫助信息，具有詳細的類樹信息、索引信息等，并提供了許多相關類之間的關系，如繼承、實現接口等。

Java文檔全是由一些HTML文件組織起來的，在Sun公司的站點上可以下載它們的壓縮包。打開Java API文檔后，可以看到如圖1-36所示的內容。該HTML格式的文檔包含了許多超鏈接。

Java系統提供的javadoc工具可以根據程序結構自動產生注釋文檔。當程序修改時，可方便、及時地更新生成的注釋文檔。javadoc.exe工具存在于JDK的bin目錄下，使用javadoc將讀取．java源文件中的文檔注釋，并按照一定的規則與Java源程序一起進行編譯，生成文檔。所輸出的文件是HTML格式的，可以通過Web瀏覽器查看。

【例1-3】 用javadoc生成下面程序HelloDate.java的文檔。

        //文件名：HelloDate.java
        import java.util.*;
        public class HelloDate {
            public static void main(String[] args) {
                System.out.println("Hello, it's: ");
                System.out.println(new Date());
            }
        }

程序運行結果如下：

        Hello, it's:
        Thu Dec 16 10:04:15 CST 2010

運行以下命令，為程序自動生成文檔，界面如圖1-37所示。

        javadoc  HelloDate.java

javadoc在當前目錄下生成了許多HTML文件，這些就是程序文檔。其中，index.html文件是起始文檔。打開該文件，顯示內容如圖1-38所示。

javadoc標記是插入文檔注釋中的特殊標記，它們主要用于標識代碼中的特殊引用。javadoc標記由“@”及其后所跟的標記類型和專用注釋引用組成。javadoc的主要標記如表1-2所示。

執行javadoc命令的一般格式如下：

javadoc [options] [packages] [sourcefiles] [@files]

在命令中有4組可選項，方括號本身不是命令的一部分。命令行的每個選項之間用一個或多個空格分開。各組選項的用途如表1-3所示。

javadoc中options選項很多，表1-4列出了比較常用的選項。

用戶可以使用如下命令處理當前目錄下的一個源文件中所有的類和成員：

      javadoc  -author  -version  -private  *.java

該命令為所有的類和成員生成文檔注釋并輸出作者和版本信息。