woaidongmao

    Javadoc是Sun公司提供的一個技術，它從程序源代碼中抽取類、方法、成員等注釋形成一個和源代碼配套的API幫助文檔。也就是說，只要在編寫程序時以一套特定的標簽作注釋，在程序編寫完成后，通過Javadoc就可以同時形式程序的開發文檔了。
Javadoc輸出的是一些HTML文件，我們可以通過WEB瀏覽器來查看它。
Javadoc的語法：
所有Javadoc都只能源于/**開始和*/結束。使用javadoc有二種方式：一種是嵌入HTML；另一種是使用文檔標簽。所謂文檔標簽就是一些以 “@”開頭的命令，且“@”要置于注釋行的最前面。而“行內文檔標簽”則可以出現在Javadoc注釋中的任何地方，它們也是以“@”字符開頭，但要括在共括號內。
Javadoc只能為public或者protected成員進行文檔注釋。private和包內訪問的成員的注釋會被忽略掉。這樣做是有道理的，因為只有public和protected成員才能在文件之外被使用，這也體現了封裝性的優點。
嵌入HTML:
Javadoc將HTML代碼嵌入到所生成的HTML文件中。這樣能充分利用HTML的功能。比如：
/**
*<b>
*this is my test program;
*</b>
*/
但一般我們不要在HTML里使用標題，如<h1><hr>，因為Javadoc會插入自己的標題，我們的標題可能會干擾它。
常用的標簽：
1) @see:引用其它類的文檔，相當于超鏈接，Javadoc會在其生成的HTML文件中，將@see標簽鏈到其他的文檔
@see classname
這樣在生成的文檔中會出現"See Also"的超鏈蛸。但是Javadoc不去檢查你的超鏈接是否有效。
2) {@link package.class#member label}
與@See的功能一樣，只是用label作主超鏈接，而不是用"see also"
3) {@docRoot}：標簽產生 到文檔根目錄的相對路徑，用于文檔樹頁面的顯式超鏈接
4) {@inheritDoc}:標簽從當前這個類的最直接的基類中繼承相關文檔到當前的文檔注釋中。
5) @version：使用方法為@version 2.2.1.2...
      2.2.1.2...是我們作的版本說明信息
6) @author:使用方法為 @author PowerFedora powpro@hotmail.com
      也就是說我們可以在@author后加上作者名字，email等聯系方式
7) @since：這個標簽允許你指定程序最早使用的版本。
      比如我們看JDK Document里的每個類最后都會說明從JDK哪個版本開始啟用。
8) @param：@param name 用于輸入客戶的姓名
      @param后面是方法的參數，以及相應的說明
      我們可以使用任意數量的此標簽，每個參數都可以有這樣一個標簽
9) @return this is description
      @return后面是描述返回值的含義，可以延續幾行。
10) @throws fully-qualified-class-name description
      fully-qualified-class-name為異常類的完整名字，
      而description告訴你為什么此異常會在方法中調用出現。
11) @deprecated:用于指出一些舊特性已由改進的新特性所取代，建議用戶不要再使用舊特性。

Sample：

import java.util.*;
/** 這是一個為了測試Javadoc而專門寫的類
* 功能是打印字符串 HelloWorld
* @author AuthorName
* @version 1.0
*/
public class JavaDocTest {

/** 這里的main函數，作為java程序的入口
  * @param 參數為一個String對象數組
  * @return 沒有返回值的內容
  * @exception exceptions 沒有異常被拋出
  */
public static void main(String[] args){
     System.out.print("HelloWorld!");    
}
}
如果使用eclipse的話，完全不需要背這些標簽。在需要注釋的地方打上/**之后，再打@符號eclipse會自動顯示所支持的標簽供選擇。
同樣在生成HTML文檔時也可以利用eclipse的export功能直接導出，否則用javadoc手工來生成的話是件相當痛苦的事情。

========================================================================

========================================================================