目錄：
- 1. 在代碼中使用文檔注釋
- 2. 類注釋
- 3. 方法注釋
- 4. 域注釋
- 5. 通用注釋
- 6. 包與概述注釋
- 7. 注釋的抽取
1. 在代碼中使用文檔注釋
Java 程式員在開發的過程中，或多或少都會有查閱 API（Application Programming Interface）文檔的需求，層次分明的 API 文檔給 Java 開發帶來了極大的便利。那麼，我們有沒有辦法給自己的程式，也“編寫”這樣一個結構化的文檔呢？答案當然是肯定的！
JDK 包含一個很有用的工具，叫做 javadoc, 它可以由 Java 源檔案生成一個HTML文檔，隻需要在源代碼中添加相對應的以 結束的注釋，然後利用 javadoc 指令，就可以為自己的程式生成類似 Java API 的文檔！
這是一種很好的方式，因為這種方式可以将代碼與注釋儲存在一個地方。如果将文檔存人一個獨立的檔案中，就有可能會随着時間的推移，出現代碼和注釋不一緻的問題。然而，如果文檔注釋與源代碼在同一個檔案中，在修改源代碼的同時，重新運作 javadoc 就可以輕而易舉地保持兩者的一緻性。
編寫Java程式時，需為以下部分插入文檔注釋：
- 包
- 公有類與接口
- 公有的和受保護的構造器及方法
- 公有的和受保護的域
2. 類注釋
類注釋必須放在 import 語句之後，類定義之前。例如：
import com.jujunjian.demo.Person;
/**
* Describe your class
*
* @version 1.0 2020-11-07
* @author JuJunjian
*/
public class Student extends Person {
}
3. 方法注釋
每一個方法注釋必須放在所描述的方法之前。對于方法而言，還可以使用下面的标記：
- @param：對方法的參數變量進行描述。
- @return：對方法的傳回值進行描述。
- @throws：用于表示這個方法有可能抛出異常。
/**
* 一個尋找清單中元素（Integer類型）最大值的方法
* @param list 搜尋最大值的清單
* @return max list中的最大值
*/
public Integer getMax(List<Integer> list){
Integer max = 0;
// 方法的具體實作
return max;
}
4. 域注釋
隻需要對公有域（通常指的是靜态常量）建立文檔。例如：
/**
* The "Hearts" card suit
*/
public static final int HEARTS = 1;
5. 通用注釋
- @author 姓名
- @version 版本
-
@since 文本
這個标記将産生一個“ since” （始于）條目。這裡的 text 可以是對引人特性的版本描 述。例如，©since version 1.7.10
-
@deprecated 文本
這個标記将對類、方法或變量添加一個不再使用的注釋。
-
@see/@link 引用
通過 @see 和 @link 标記，可以使用超級連結，連結到 javadoc 文檔的相關部分或外部文檔。
6. 包與概述注釋
可以直接将類、方法和變量的注釋放置在 Java 源檔案中，隻要用 文檔注釋界定就可以了。但是，要想産生包注釋，就需要在每一個包目錄中添加一個單獨的檔案。
可以 有如下兩個選擇：
- 提供一個以 package.html 命名的 HTML 檔案。在标記
<body>...</body>
- 提供一個以 package-info.java命名的 Java 檔案。這個檔案必須包含一個初始的以 界定的 Javadoc 注釋，跟随在一個包語句之後。它不應該包含更多的代碼或注釋。
- 還可以為所有的源檔案提供一個概述性的注釋。這個注釋将被放置在一個名為overview.html 的檔案中，這個檔案位于包含所有源檔案的父目錄中。标記
<body>... </body>
7. 注釋的抽取
這裡，假設 HTML 檔案将被存放在目錄 docDirectory 下，執行以下步驟：
- 切換到包含想要生成文檔的源檔案目錄。如果有嵌套的包要生成文檔，例如com.horstmann.corejava，就必須切換到包含子目錄com的目錄（如果存在 overview.html 檔案的話，這也是它的所在目錄)。
-
如果是一個包，應該運作指令:
javadoc -d docDirectory nameOfPackage
-
對于多個包生成文檔，運作:
javadoc -d docDirectory nameOfPackage1 nameOfPackage2…
-
如果檔案在預設包中，就應該運作：
javadoc -d docDirectory *.java
如果省略了 -d docDirectory 選項，那 HTML 檔案就會被提取到目前目錄下。這樣有可能會帶來混亂，是以不提倡這種做法。
在提取文檔注釋時經常需要指定編碼方式，加上 -encoding charset 可以指定編碼方式（charset處填寫編碼方式，如 UTF-8）。例如：
javadoc -d Document -encoding UTF-8 com.jujunjian.client com.jujunjian.server com.jujunjian.view
生成成功之後，在src目錄下新增了一個Document檔案夾，提取出來的文檔就被放在這個檔案夾裡：
連結：點選此處以下載下傳示例資源
更多需求可以在指令行中輸入 javadoc -help 檢視，用浏覽器打開上述示例中 Document 檔案夾下的 index.html 檔案，浏覽器中會出現如下圖所示的内容：
利用 javadoc，就可以為自己的代碼生成類似 Java API 的 HTML 文檔了，感興趣的小夥伴不妨也嘗試下為自己的程式“編寫”一份清晰的說明書吧！