Javadoc 註釋規範全攻略：從基礎語法到企業級文檔生成
一、三種註釋類型對比
| 語法 | 用途 | 文檔生成 |
|---|
// 單行註釋 | 代碼說明 | 否 |
/* 多行註釋 */ | 代碼塊說明 | 否 |
/** 文檔註釋 */ | API 文檔 | 是 |
標準文檔註釋格式
/**
* 簡述：第一句話以句號結束，會顯示在摘要表中。
* <p>
* 詳細說明：可包含 HTML 標籤（<br>、<p>、<code>、<ul> 等）。
*
* @param 參數名 參數說明
* @return 返回值說明
* @throws 異常類名 異常觸發條件
* @author 作者名
* @version 版本號
* @see 相關類/方法引用
* @since 版本號
* @deprecated 棄用說明及替代方案
*/
二、文檔註釋三部分結構
- 簡述：首句話（含句號），出現在類/方法摘要表
- 詳細說明：深度闡述，可多段落、含 HTML
- 標籤塊：@param、@return、@throws、@see 等結構化元數據
實戰範例
/**
* 根據用戶 ID 查詢用戶詳情。
* <p>
* 若用戶不存在返回 null，不拋出異常。
* 支援緩存查詢，首次查詢後結果寫入 Redis（TTL 30min）。
*
* @param userId 用戶唯一標識，必須 > 0
* @return User 對象，不存在返回 null
* @throws IllegalArgumentException userId <= 0
* @see UserService#save(User)
* @since 2.1.0
*/
public User findById(Long userId) { ... }
三、常用 Javadoc 標籤詳解
| 標籤 | 適用對象 | 說明 |
|---|
@author | 類/介面 | 作者，可多個，按時間序 |
@version | 類/介面 | 版本號，僅首個生效 |
@param | 方法/構造器 | 參數名 + 說明，按聲明順序 |
@return | 方法 | 返回值說明，void 可省略 |
@throws/@exception | 方法 | 異常類 + 觸發條件，按字母序 |
@see | 所有 | 引用關聯，支援 #method、Class#field 等 |
@since | 類/方法 | 引入版本，如 @since 1.8 |
@deprecated | 所有 | 棄用說明 + 替代方案 + @see |
{@link} | 文中 | 行內連結：{@link UserService#save(User)} |
{@code} | 文中 | 行內代碼：{@code null} |
四、Javadoc 命令行工具
基本用法
javadoc -d 輸出目錄 -author -version -encoding UTF-8 源文件或包名
常用選項
-public/-protected/-package/-private：控制輸出可見性層級-d <dir>：輸出目錄-windowtitle <text>：瀏覽器標題-splitindex：按字母拆分索引文件-subpackages pkg：遞歸處理子包
執行示例
# 按包生成
javadoc -d docs -subpackages com.myapp
# 按文件生成
javadoc -d docs com/myapp/UserService.java com/myapp/User.java
五、企業級編碼規範建議
1. 文件頭註釋
/**
* @title UserService.java
* @description 用戶業務邏輯服務層
* @company ABC Tech
* @author Zhang San
* @version 1.0.0
* @date 2024-01-15
*/
2. 類/介面註釋
- 必填：@author、@version、@since
- 描述職責、設計模式、線程安全性
- @see 關聯核心協作類
3. 方法註釋
- 公共 API 強制編寫完整註釋
- @param 覆蓋所有參數，說明約束條件
- @return 語義化描述，含 null/空集合情況
- @throws 列出所有受檢異常 + 業務異常
4. 字段/常量註釋
/** 最大重試次數，超過即判定失敗 */
public static final int MAX_RETRY = 3;
/** 用戶緩存 Key 前綴：user:{id} */
private static final String CACHE_PREFIX = "user:";
六、HTML 標籤在註釋中的使用
<p> 段落分隔（必須，換行符不生效）<br> 強制換行<code> / <pre> 代碼片段<ul><li> 列表<table> 表格（如參數對照表）
七、IDE 整合與持續集成
- IntelliJ IDEA：Settings → Build → Javadoc，配置輸出路徑、編碼、標籤
- Maven：
maven-javadoc-plugin 綁定 site 階段自動生成
- CI/CD：發布階段自動部署 Javadoc 至內部文檔站
總結
規範的 Javadoc 註釋是 API 文檔化、團隊協作、新人上手的基石。養成「寫代碼即寫文檔」習慣，配合 IDE 提示與 CI 自動發布，讓文檔永遠與代碼同步演進。
