JavaDoc，在 Java 的注釋上做文章(上)

　　對於Java注釋我們主要了解兩種
　　// 注釋一行
　　/* */ 注釋若干行
　　但還有第三種文檔注釋
　　/** */ 注釋若干行並寫入 javadoc 文檔
　　通常這種注釋的多行寫法如下
　　/**
　　*
　　*
　　*/
　　很多人多忽視了這第三種注釋那麼這第三種注釋有什麼用？javadoc 又是什麼東西？下面我們就談談
　　一 Java 文檔和 Javadoc
　　Java 程序員都應該知道使用 JDK 開發最好的幫助信息就來自 SUN 發布的 Java 文檔它分包分類詳細的提供了各方法屬性的幫助信息具有詳細的類樹信息索引信息等並提供了許多相關類之間的關系如繼承實現接口引用等
　　Java 文檔全是由一些 html 文件組織起來的在 SUM 的站點上可以下載它們的壓縮包但是你肯定想不到這些文檔我們可以自己生成——就此打住再吊一次胃口
　　安裝了 JDK 之後安裝目錄下有一個 srcjar 文件或者 srczip 文件它們都是以 ZIP 格式壓縮的可以使用 WinZip 解壓解壓之後我們就可以看到分目錄放的全是 java 文件是了這些就是 Java 運行類的源碼了非常完整連注釋都寫得一清二楚……不過怎麼看這些注釋都有點似曾相識的感覺？
　　這就不奇怪了我們的迷底也快要揭開了如果你仔細對比一下 java 源文件中的文檔注釋 (/** */) 和 Java 文檔的內容你會發現它們就是一樣的Java 文檔只是還在格式和排版上下了些功夫再仔細一點你會發現 java 源文件中的注釋還帶有 HTML 標識如 ＜B＞＜BR＞＜Code＞ 等在 Java 文檔中該出現這些標識的地方已經按標識的的定義進行了排版
　　終於真像大白了原來 Java 文檔是來自這些注釋難怪這些注釋叫做文檔注釋呢！不過是什麼工具把這些注釋變成文檔的呢？
　　是該請出 javadoc 的時候了在 JDK 的 bin 目錄下你可以找到 javadoc如果是 Windows 下的 JDK它的文件名為 javadocexe使用 javdoc 編譯 java 源文件時它會讀出 java 源文件中的文檔注釋並按照一定的規則與 Java 源程序一起進行編譯生成文檔
　　介紹 javadoc 的編譯命令之前還是先了解一下文檔注釋的格式吧不過為了能夠編譯下面提到的若干例子這裡先介紹一條 javadoc 命令
　　javadoc d 文檔存放目錄 author version 源文件名java
　　這條命令編譯一個名為 源文件名java的 java 源文件並將生成的文檔存放在文檔存放目錄指定的目錄下生成的文檔中 l 就是文檔的首頁author 和 version 兩上選項可以省略
　　二 文檔注釋的格式
　　文檔注釋可以用於對類屬性方法等進行說明寫文檔注釋時除了需要使用 /** */ 限定之外還需要注意注釋內部的一些細節問題
　　 文檔和文檔注釋的格式化
　　生成的文檔是 HTML 格式而這些 HTML 格式的標識符並不是 javadoc 加的而是我們在寫注釋的時候寫上去的比如需要換行時不是敲入一個回車符而是寫入 ＜br＞如果要分段就應該在段前寫入 ＜p＞
　　因此格式化文檔就是在文檔注釋中添加相應的 HTML 標識
　　文檔注釋的正文並不是直接復制到輸出文件 (文檔的 HTML 文件)而是讀取每一行後刪掉前導的 * 號及 * 號以前的空格再輸入到文檔的如
　　/**
　　* This is first line ＜br＞
　　***** This is second line ＜br＞
　　This is third line
　　*/　
　　編譯輸出後的 HTML 源碼則是
　　This is first line ＜br＞
　　This is second line ＜br＞
　　This is third line　
　　前導的 * 號允許連續使用多個其效果和使用一個 * 號一樣但多個 * 號前不能有其它字符分隔否則分隔符及後面的 * 號都將作為文檔的內容* 號在這裡是作為左邊界使用如上例的第一行和第二行如果沒有前導的 * 號則邊界從第一個有效字符開始而不包括前面的空格如上例第三行
　　還有一點需要說明文檔注釋只說明緊接其後的類屬性或者方法如下例
　　/** comment for class */
　　public class Test {
　　/** comment for a attribute */
　　int number;
　　/** comment for a method */
　　public void myMethod() { }
　　
　　}
　　上例中的三處注釋就是分別對類屬性和方法的文檔注釋它們生成的文檔分別是說明緊接其後的類屬性方法的緊接二字尤其重要如果忽略了這一點就很可能造成生成的文檔錯誤如
　　import javalang*;
　　/** commnet for class */
　　public class Test { }
　　// 此例為正確的例子
　　這個文檔注釋將生成正確的文檔但只需要改變其中兩行的位置變成下例就會出錯
　　/** commnet for class */
　　import javalang*;
　　public class Test { }
　　// 此例為錯誤的例子
　　這個例子只把上例的 import 語句和文檔注釋部分交換了位置結果卻大不相同——生成的文檔中根本就找不到上述注釋的內容了原因何在？
　　/** commnet for class */是對 class Test 的說明把它放在public class Test { }之前時其後緊接著 class Test符合規則所以生成的文檔正確但是把它和import javalang*;調換了位置後其後緊接的就是不 class Test 了而是一個 import 語句由於文檔注釋只能說明類屬性和方法import 語句不在此列所以這個文檔注釋就被當作錯誤說明省略掉了
　　 文檔注釋的三部分
　　根據在文檔中顯示的效果文檔注釋分為三部分先舉例如下以便說明
　　/**
　　* show 方法的簡述
　　* ＜p＞show 方法的詳細說明第一行＜br＞
　　* show 方法的詳細說明第二行
　　* @param b true 表示顯示false 表示隱藏
　　* @return 沒有返回值
　　*/
　　public void show(boolean b) {
　　frameshow(b);
　　}
　　第一部分是簡述文檔中對於屬性和方法都是先有一個列表然後才在後面一個一個的詳細的說明列表中屬性名或者方法名後面那段說明就是簡述如下圖中被紅框框選的部分
　　　
　　簡述部分寫在一段文檔注釋的最前面第一個點號 () 之前 (包括點號)換句話說就是用第一個點號分隔文檔注釋之前是簡述之後是第二部分和第三部分如上例中的 * show 方法的簡述
　　有時即使正確地以一個點號作為分隔javadoc 仍然會出錯把點號後面的部分也做為了第一部分為了解決這個問題我們可以使用一個 ＜p＞ 標志將第二分部分開為下一段如上例的* ＜p＞show 方法的詳細說明第一行 除此之外我們也可以使用 ＜br＞ 來分隔
　　第二部分是詳細說明部分該部分對屬性或者方法進行詳細的說明在格式上沒有什麼特殊的要求可以包含若干個點號它在文檔中的位置如下圖所示
　　　
　　這部分文檔在上例中相應的代碼是
　　* show 方法的簡述
　　* ＜p＞show 方法的詳細說明第一行＜br＞
　　* show 方法的詳細說明第二行
　　發現什麼了？對了簡述也在其中這一點要記住了不要畫蛇添足——在詳細說明部分中再寫一次簡述哦！
　　第三部分是特殊說明部分這部分包括版本說明參數說明返回值說明等它在文檔中的位置
　　　
　　第三部分在上例中相應的代碼是
　　* @param b true 表示顯示false 表示隱藏
　　* @return 沒有返回值
　　除了 @param 和 @return 之外還有其它的一些特殊標記分別用於對類屬性和方法的說明……不要推我我馬上就說
　　三 使用 javadoc 標記
　　javadoc 標記是插入文檔注釋中的特殊標記它們用於標識代碼中的特殊引用javadoc 標記由@及其後所跟的標記類型和專用注釋引用組成記住了三個部分——@標記類型專用注釋引用不過我寧願把它分成兩部分@ 和標記類型專用注釋引用雖然 @ 和 標記類型之間有時可以用空格符分隔但是我寧願始終將它們緊挨著寫以減少出錯機會
　　javadoc 標記有如下一些
　　　
　　下面詳細說明各標記
　　 @see 的使用
　　@see 的句法有三種
　　@see 類名
　　@see #方法名或屬性名
　　@see 類名#方法名或屬性名
　　類名可以根據需要只寫出類名 (如 String) 或者寫出類全名 (如 javalangString)那麼什麼時候只需要寫出類名什麼時候需要寫出類全名呢？
　　如果 java 源文件中的 import 語句包含了的類可以只寫出類名如果沒有包含則需要寫出類全名javalang 也已經默認被包含了這和 javac 編譯 java 源文件時的規定一樣所以可以簡單的用 javac 編譯來判斷源程序中 javac 能找到的類javadoc 也一定能找到javac 找不到的類javadoc 也找不到這就需要使用類全名了
　　方法名或者屬性名如果是屬性名則只需要寫出屬性名即可如果是方法名則需要寫出方法名以及參數類型沒有參數的方法需要寫出一對括號如
　　　
　　有時也可以偷懶假如上例中沒有 count 這一屬性那麼參考方法 count() 就可以簡寫成 @see count不過為了安全起見還是寫全 @see count() 比較好
　　@see 的第二個句法和第三個句法都是轉向方法或者屬性的參考它們有什麼區別呢？
　　第二
From:http://tw.wingwit.com/Article/program/Java/JSP/201311/19537.html