關於Java的注釋

對於Java注釋我們主要瞭解兩種：

// 注釋一行

/* ...... */ 注釋若干行

但還有第三種，文檔注釋：

/** ...... */ 注釋若干行，並寫入 javadoc 文檔

通常這種注釋的多行寫法如下：

/**

* .........

* .........

*/

很多人多忽視了這第三種注釋，那麼這第三種注釋有什麼用？javadoc 又是什麼東西？下面我們就談談。

一. Java 文檔和 Javadoc

Java 程式員都應該知道使用 JDK 開發，最好的協助資訊就來自 SUN 發布的 Java 文檔。它分包、分類詳細的提供了各方法、屬性的協助資訊，具有詳細的類樹資訊、索引資訊等，並提供了許多相關類之間的關係，如繼承、實現介面、引用等。

Java 文檔全是由一些 html 檔案組織起來的，在 SUM 的網站上可以下載它們的壓縮包。但是你肯定想不到，這些文檔我們可以自己產生。——就此打住，再吊一次胃口。

安裝了 JDK 之後，安裝目錄下有一個 src.jar 檔案或者 src.zip 檔案，它們都是以 ZIP 格式壓縮的，可以使用 WinZip 解壓。解壓之後，我們就可以看到分目錄放的全是 .java 檔案。是了，這些就是 Java 運行類的源碼了，非常完整，連注釋都寫得一清二楚……不過，怎麼看這些注釋都有點似曾相識的感覺？

這就不奇怪了，我們的迷底也快要揭開了。如果你仔細對比一下 .java 源檔案中的文檔注釋 (/** ... */) 和 Java 文檔的內容，你會發現它們就是一樣的。Java 文檔只是還在格式和排版上下了些功夫。再仔細一點，你會發現 .java 源檔案中的注釋還帶有 HTML 標識，如 ＜B＞、＜BR＞、＜Code＞ 等，在 Java 文檔中，該出現這些標識的地方，已經按標識的的定義進行了排版。

終於真像大白了，原來 Java 文檔是來自這些注釋。難怪這些注釋叫做文檔注釋呢！不過，是什麼工具把這些注釋變成文檔的呢？

是該請出 javadoc 的時候了。在 JDK 的 bin 目錄下你可以找到 javadoc，如果是 Windows 下的 JDK，它的檔案名稱為 javadoc.exe。使用 javdoc 編譯 .java 源檔案時，它會讀出 .java 源檔案中的文檔注釋，並按照一定的規則與 Java 來源程式一起進行編譯，產生文檔。

介紹 javadoc 的編譯命令之前，還是先瞭解一下文檔注釋的格式吧。不過為了能夠編譯下面提到的若干例子，這裡先介紹一條 javadoc 命令：

javadoc -d 文檔存放目錄 -author -version 源檔案名稱.java

這條命令編譯一個名為 “源檔案名稱.java”的 java 源檔案，並將產生的文檔存放在“文檔存放目錄”指定的目錄下，產生的文檔中 index.html 就是文檔的首頁。-author 和 -version 兩上選項可以省略。