1. 文檔注釋
Java 文檔注釋(Java Doc Comments)是專門為了用javadoc工具自動生成文檔而寫的注釋，文檔注釋與一般注釋的最大區別在於起始符號是/**而不是/*或//。
文檔注釋只負責描述類(class)、接口(interface)、方法(method)、構造器(constructor)、成員字段(field)。相應地，文檔注釋必須寫在類、接口、方法、構造器、成員字段前面，而寫在其他位置，比如函數內部，是無效的文檔注釋。
文檔注釋采用HTML語法規則書寫，支持HTML標記(tag)，同時也有一些額外的輔助標記。需要注意的是，這些標記不是給人看的（通常他們的可讀性也不好），可以通過 Javadoc 命令把文檔注釋中的內容生成文檔，並輸出到 HTML 文件中
1.1 文檔格式
在類上的文檔標注一般分為三段：
第一段：概要描述，通常用一句或者一段話簡要描述該類的作用，以英文句號作為結束
第二段：詳細描述，通常用一段或者多段話來詳細描述該類的作用，一般每段話都以英文句號作為結束
第三段：文檔標注，用於標注作者、創建時間、參閱類等信息
生成文檔是HTML格式。
換行<br>
分段<p>(寫在段前）)
1.2 Javadoc標簽
Javadoc 工具可以識別文檔注釋中的一些特殊標簽，這些標簽一般以@開頭，后跟一個指定的名字，有的也以{@開頭，以}結束。Javadoc 可以識別的標簽如下表所示：
| 標簽 | 描述 | 標簽類型 |
|---|---|---|
| @author | 作者標識 | 包、 類、接口 |
| @deprecated | 標識當前API已經過期，僅為了保證兼容性依然存在，以此告之開發者不應再用這個API | 包、類、接口、值域、構造函數、 方法 |
| {@docRoot} | 指明當前文檔根目錄的路徑 | |
| @exception | 標志一個類拋出的異常 | 構造函數、 方法 |
| {@inheritDoc} | 從直接父類繼承的注釋 | |
| {@link} | 鏈接到某個特定的成員對應的文檔中 | 包、類、接口、值域、構造函數、 方法 |
| {@linkplain} | 插入一個到另一個主題的鏈接，但是該鏈接顯示純文本字體 | 包、類、接口、值域、構造函數、 方法 |
| @param | 方法的入參名及描述信息，如入參有特別要求，可在此注釋 | 構造函數、方法 |
| @return | 對函數返回值的注釋 | 方法 |
| @see | 引用,查看相關內容，如類、方法、變量等 | 包、類、接口、值域、構造函數、 方法 |
| @serial | 說明一個序列化屬性 | |
| @serialData | 說明通過writeObject( ) 和 writeExternal( )方法寫的數據 | |
| @serialField | 說明一個ObjectStreamField組件 | @ |
| @since | 描述文本,API在什么程序的什么版本后開發支持 | 包、類、接口、值域、構造函數、 方法 |
| @throws | 構造函數或方法所會拋出的異常 | 構造函數、 方法 |
| {@value} | 顯示常量的值，該常量必須是static屬性 | 靜態值域 |
| @version | 版本號 | 包、 類、接口 |
對兩種標簽格式的說明：
-
@tag 格式的標簽（不被{ }包圍的標簽）為塊標簽，只能在主要描述（類注釋中對該類的詳細說明為主要描述）后面的標簽部分（如果塊標簽放在主要描述的前面，則生成 API 幫助文檔時會檢測不到主要描述）。
-
{@tag} 格式的標簽（由{ }包圍的標簽）為內聯標簽，可以放在主要描述中的任何位置或塊標簽的注釋中。
Javadoc 標簽注意事項：
-
Javadoc 標簽必須從一行的開頭開始，否則將被視為普通文本。
-
一般具有相同名稱的標簽放在一起。
-
Javadoc 標簽區分大小寫，代碼中對於大小寫錯誤的標簽不會發生編譯錯誤，但是在生成 API 幫助文檔時會檢測不到該注釋內容。
2. 例子
文檔注釋可以在自己的 IDE 上定義成模板，這樣每次通過快捷鍵就可自動幫你輸出在代碼中，節省時間，也使代碼規范。
文件注釋：
/*
* <p>項目名稱: ${project_name} </p>
* <p>文件名稱: ${file_name} </p>
* <p>描述: [類型描述] </p>
* <p>創建時間: ${date} </p>
* @author：<a href="mail to: *******@******.com" rel="nofollow">作者</a>
* @version：
* @update [序號][日期YYYY-MM-DD] [更改人姓名][變更描述]
*/
方法注釋：
/**
* @Title：${enclosing_method}
* @Description: [功能描述]
* @Param: ${tags}
* @Return: ${return_type}
* @author：<a href="mail to: *******@******.com" rel="nofollow">作者</a>
* @CreateDate: ${date} ${time}</p>
* @update: [序號][日期YYYY-MM-DD] [更改人姓名][變更描述]
*/
3 生成文檔
3.1 使用javadoc生成文檔
Javadoc 是 Sun 公司提供的一個技術，它從程序源代碼中抽取類、方法、成員等注釋,然后形成一個和源代碼配套的API幫助文檔。也就是說，只要在編寫程序時以一套特定的標簽作注釋，在程序編寫完成后，通過Javadoc就可以同時形成程序的 API 幫助文檔。
API 幫助文檔相當於產品說明書，而說明書只需要介紹那些供用戶使用的部分，所以 Javadoc 默認只提取 public、protected 修飾的部分。如果要提取 private 修飾的部分，需要使用 -private。
如果是第一次使用javadoc命令，可以通過javadoc -help命令查看javadoc使用說明。
例:
javadoc -d 文檔存放目錄 -author -version 源文件名.java
這條命令編譯一個名為"源文件名.java"的 java 源文件，並將生成的文檔存放在"文檔存放目錄"指定的目錄下，生成的文檔中 index.html 就是文檔的首頁。-author 和 -version 兩個選項可以省略
Javadoc 並不是將代碼中的文檔注釋直接復制到幫助文檔的 HTML 文件中，而是讀取每一行后，刪除前面的號及以前的空格再輸入到 HTML 文檔。注釋前面的號允許連續使用多個，其效果和使用一個號一樣，但多個前不能有其他字符分隔，否則分隔符及后面的號都將作為文檔的內容。
3.2 通過IDEA生成Javadoc
菜單：Tools -> Generate JavaDoc
注意要配置編碼，如果不配置則生成的JavaDoc會亂碼，還需要配置Output directory
這里有幾點要特別注意一下：
- 注意生成 JavaDoc 的源代碼對象的選擇，一般以模塊（Module）為主，必要時可以單獨選擇必要的 Java 源代碼文件，不推薦以 Project 為 JavaDoc 生成的源范圍。
- 里面有一個 Locale 可選填項，表示的是需要生成的 JavaDoc 以何種語言版本展示，根據 javadoc.exe 的幫助說明，這其實對應的就是 javadoc.exe 的 -locale 參數，如果不填，默認可能是英文或者是當前操作系統的語言，既然是國人，建議在此填寫 zh_CN，這樣生成的 JavaDoc 就是中文版本的，當然指的是 JavaDoc 的框架中各種通用的固定顯示區域都是中文的。你自己編寫的注釋轉換的內容還是根據你注釋的內容來。
- 還有一個“Other command line arguments:”可選填項，非常重要，是填寫直接向 javadoc.exe 傳遞的參數內容。因為有一些重要的設置，只能通過直接參數形式向 javadoc.exe 傳遞。例如：
``
-encoding UTF-8 -charset UTF-8 -windowtitle "" -link https://
- 第一個參數 -encoding UTF-8 表示你的源代碼（含有符合 JavaDoc 標准的注釋）是基於 UTF-8 編碼的，以免處理過程中出現中文等非英語字符亂碼；
- 第二個參數 -charset UTF-8 表示在處理並生成 JavaDoc 超文本時使用的字符集也是以 UTF-8 為編碼；
- 第三個參數 -windowtitle 表示生成的 JavaDoc 超文本在瀏覽器中打開時，瀏覽器窗口標題欄顯示的文字內容；
- 第四個參數 -link 很重要，它表示你生成的 JavaDoc 中涉及到很多對其他外部 Java 類的引用，是使用全限定名稱還是帶有超鏈接的短名稱，舉個例子，我創建了一個方法 public void func(String arg)，這個方法在生成 JavaDoc 時如果不指定 -link 參數，則 JavaDoc 中對該方法的表述就會自動變為 public void func(java.lang.String arg)，因為 String 這個類對我自己實現的類來講就是外部引用的類，雖然它是 Java 標准庫的類。如果指定了 -link https://docs.oracle.com/javase/8/docs/api/ 參數，則 javadoc.exe 在生成 JavaDoc 時，會使用 String 這樣的短名稱而非全限定名稱 java.lang.String，同時自動為 String 短名稱生成一個超鏈接，指向官方 JavaSE 標准文檔 https://docs.oracle.com/javase/8/docs/api/ 中對 String 類的詳細文檔地址。-link 實質上是告訴 javadoc.exe 根據提供的外部引用類的 JavaDoc 地址去找一個叫 package-list 的文本文件，在這個文本文件中包含了所有外部引用類的全限定名稱，因此生成的新 JavaDoc 不必使用外部引用類的全限定名，只需要使用短名稱，同時可以自動創建指向其外部引用 JavaDoc 中的詳細文檔超鏈接。每個 JavaDoc 都會在根目錄下有一個 package-list 文件，包括我們自己生成的 JavaDoc。
#4. 阿里巴巴《Java 開發手冊-嵩山版》注釋規約（版權歸阿里巴巴《Java 開發手冊-嵩山版》所有）
1. 【強制】類、類屬性、類方法的注釋必須使用 Javadoc 規范，使用/**內容*/格式，不得使用// xxx 方式。
說明：在 IDE 編輯窗口中，Javadoc 方式會提示相關注釋，生成 Javadoc 可以正確輸出相應注釋；在 IDE 中，工程調用方法時，不進入方法即可懸浮提示方法、參數、返回值的意義，提高閱讀效率。
2. 【強制】所有的抽象方法（包括接口中的方法）必須要用 Javadoc 注釋、除了返回值、參數、異常說明外，還必須指出該方法做什么事情，實現什么功能。
說明：對子類的實現要求，或者調用注意事項，請一並說明。
3. 【強制】所有的類都必須添加創建者和創建日期。
說明：在設置模板時，注意 IDEA 的@author 為`${USER}`，而 eclipse 的@author 為`${user}`，大小寫有區別，而日期的設置統一為 yyyy/MM/dd 的格式。
正例：
/**
- @author yangguanbao
- @date 2016/10/31
*/
4. 【強制】方法內部單行注釋，在被注釋語句上方另起一行，使用//注釋。方法內部多行注釋使用/* */注釋，注意與代碼對齊。
5. 【強制】所有的枚舉類型字段必須要有注釋，說明每個數據項的用途。
6. 【推薦】與其“半吊子”英文來注釋，不如用中文注釋把問題說清楚。專有名詞與關鍵字保持英文原文即可。
反例：“TCP 連接超時”解釋成“傳輸控制協議連接超時”，理解反而費腦筋。
7. 【推薦】代碼修改的同時，注釋也要進行相應的修改，尤其是參數、返回值、異常、核心邏輯等的修改。
說明：代碼與注釋更新不同步，就像路網與導航軟件更新不同步一樣，如果導航軟件嚴重滯后，就失去了導航的意義。
8. 【推薦】在類中刪除未使用的任何字段、方法、內部類；在方法中刪除未使用的任何參數聲明與內部變量。
9. 【參考】謹慎注釋掉代碼。在上方詳細說明，而不是簡單地注釋掉。如果無用，則刪除。
說明：代碼被注釋掉有兩種可能性：1）后續會恢復此段代碼邏輯。2）永久不用。前者如果沒有備注信息，難以知曉注釋動機。后者建議直接刪掉即可，假如需要查閱歷史代碼，登錄代碼倉庫即可。
10.【參考】對於注釋的要求：第一、能夠准確反映設計思想和代碼邏輯；第二、能夠描述業務含義，使別的程序員能夠迅速了解到代碼背后的信息。完全沒有注釋的大段代碼對於閱讀者形同天書，注釋是給自己看的，即使隔很長時間，也能清晰理解當時的思路；注釋也是給繼任者看的，使其能夠快速接替自己的工作。
11.【參考】好的命名、代碼結構是自解釋的，注釋力求精簡准確、表達到位。避免出現注釋的一個極端：過多過濫的注釋，代碼的邏輯一旦修改，修改注釋又是相當大的負擔。
反例：
// put elephant into fridge
put(elephant, fridge);
方法名 put，加上兩個有意義的變量名 elephant 和 fridge，已經說明了這是在干什么，語義清晰的代碼不需要額外的注釋。
12.【參考】特殊注釋標記，請注明標記人與標記時間。注意及時處理這些標記，通過標記掃描，經常清理此類標記。線上故障有時候就是來源於這些標記處的代碼。
1） 待辦事宜（TODO）:（標記人，標記時間，[預計處理時間]）
表示需要實現，但目前還未實現的功能。這實際上是一個 Javadoc 的標簽，目前的 Javadoc 還沒有實現，但已經被廣泛使用。只能應用於類，接口和方法（因為它是一個 Javadoc 標簽）。
2） 錯誤，不能工作（FIXME）:（標記人，標記時間，[預計處理時間]）在注釋中用 FIXME 標記某代碼是錯誤的，而且不能工作，需要及時糾正的情況。