三種生成入口
| 方式 | 操作路徑 | 優點 |
|---|
| 項目右鍵 | Project → Export → Java → Javadoc | 直觀、可選模塊 |
| 菜單欄 | File → Export → Java → Javadoc | 同右鍵 |
| 專用菜單 | Project → Generate Javadoc | 一鍵直達配置頁 |
關鍵配置項
- Javadoc 命令：必須指向 JDK 的
bin/javadoc.exe（非 JRE）
- Destination：輸出目錄，建議
target/site/apidocs
- 編碼設置（關鍵）：VM options 欄填入
-encoding UTF-8 -charset UTF-8 -docencoding UTF-8
解決「GBK 不可映射字符」亂碼問題
- 源碼範圍：勾選需要的包，排除生成代碼、測試代碼
- 訪問級別：Public / Protected / Package / Private
常見錯誤與解決
| 錯誤現象 | 原因 | 解決 |
|---|
java.lang.IllegalArgumentException at sun.net.www.ParseUtil.decode | 環境變量 CLASSPATH 干擾 | 刪除系統 CLASSPATH 或在 javadoc 命令加 -J-Djava.class.path= |
| 中文亂碼 / 「不可映射字符」 | 編碼不一致 | VM options 加 -encoding UTF-8 -charset UTF-8 -docencoding UTF-8 |
| 缺少標簽 / 參數未識別 | 註釋格式不規範 | 使用 @param @return @throws 標準標簽 |
Maven 整合（推薦 CI/CD 使用）
org.apache.maven.plugins
maven-javadoc-plugin
3.6.0
UTF-8
UTF-8
UTF-8
protected
*.impl,*internal*,*test*
命令：mvn javadoc:javadoc → 輸出至 target/site/apidocs
Gradle 整合
tasks.withType(Javadoc) {
options.encoding = 'UTF-8'
options.charSet = 'UTF-8'
options.addStringOption('Xdoclint:none', '-quiet')
exclude '**/impl/**', '**/internal/**', '**/test/**'
}
文檔規範建議
- 類/接口：
@author、@since、功能概述
- 公共方法：
@param、@return、@throws、@see
- 包信息：
package-info.java 編寫模塊級說明
- 使用
{@link @code @literal 增強可讀性
一鍵生成腳本
# build-doc.sh
mvn clean javadoc:javadoc -Dmaven.test.skip=true
# 輸出：target/site/apidocs/index.html
