Java使用Javadoc生成說明幫助文件
阿新 • • 發佈：2019-02-13
寫這篇文章完全是一時興起，因為在此之前，我其實也並沒有使用過 Java Doc 的功能。但是即使很少使用得到，但是你不得不承認，如果公司的API能夠整理出這麼一套API，我想每一個剛入職的員工都會對它愛不釋手的。
程式碼中註釋的使用
1. 首先看一個Demo：
import java.util.*; /** * @author WithWings * @version 1.1 * @since 1.8 */ public class HelloWorld{ public static String hello = "Hello,World!"; public static void main(String[] args){ try{ sayHello(hello); }catch(Exception e){ e.printStackTrace(); } } /** * 主專案工程執行方法，執行 .class 檔案後自動執行 mian方法 * @param s 引數 * @return 返回的引數 * @see Image * @see #hello * @exception Exception 提供異常處理 方法一 * @throws Exception 提供異常處理 方法二 */ public static String sayHello(String s) throws Exception{ System.out.println(s); System.out.println(new Date()); try{ Thread.currentThread().sleep(5 * 1000); }catch( InterruptedException e){ e.printStackTrace(); } return s; } public class Image{ /** * @deprecated 標記該API過時 */ public void printImage(){ System.out.println("Image"); } } }
- @author 作者（只出現在類和介面的文件中）
- @version 數字指的是版本號
- @since 數字指的jdk版本
- @param 指的是方法的引數，後面跟上 引數名 + 空格 + 引數說明
- @return 對返回值的說明
- @see 新增引用的類或者引數
- @see 類名
- @see #方法名或引數名
- @see 類名#引數名
- @throws 丟擲異常說明， 後面跟上 異常名 + 空格 + 異常跑出原因
2. 上面是我自己用到的，然而這些並不是很齊全，但是很幸運，我在極客學院找到一個表格，圖省事我就直接copy過來了。
| 標籤 | 描述 | 語法 | ||
|---|---|---|---|---|
| @author | 新增類的作者 | @author name-text | ||
| {@code} | 不把文字轉換成 HTML 標記和巢狀的 Java 標籤而用程式碼字型展示它 | {@code text} | ||
| {@docRoot} | 表示從任何生成頁面到生成文件的根目錄的相對路徑 | {@docRoot} | ||
| @deprecated | 新增一個註釋暗示 API 應該不再被使用 | @deprecated deprecated-text | ||
| @exception | 用類名和描述文字給生成的文件新增一個副標題 | @exception class-name description | ||
| {@inheritDoc} | 從最近的可繼承的類或可實現的介面繼承註釋 | Inherits a comment from the immediate surperclass. | ||
| {@link} | 用指向特定的包，類或者一個引用類的成員名的文件的可見文字標籤插入線上連結 | {@link package.class#member label} | ||
| {@linkplain} | 和{@link}相同，除了連結的標籤用純文字標示而不是程式碼字型 | {@linkplain package.class#member label} | ||
| @param | 給“引數”區域新增一個有特定引數名且後跟著特定描述的引數 | @param parameter-name description | ||
| @return | 新增一個有描述文字的“Returns”區域 | @return description | ||
| @see | 新增帶有連結或者指向引用的文字入口的標題“See Also” | @see reference | ||
| @serial | 在預設的序列化欄位的文字註釋中使用 | @serial field-description | include | exclude |
| @serialData | 記錄由 writeObject( ) 或 writeExternal( )方法所寫的資料 | @serialData data-description | ||
| @serialField | 記錄一個 ObjectStreamField 成分 | @serialField field-name field-type field-description | ||
| @since | 給生成的文件新增一個帶有特定 since 文字的”Since”標題 | @since release | ||
| @throws | @throw 和 @exception 標籤是同義詞 | @throws class-name description | ||
| {@value} | 當{@value}被用在一個靜態欄位的文字註釋中，它展示了那個常量的值 | {@value package.class#field} | ||
| @version | 當 -version 選項被使用時用特定的 version w文字給生成的文字新增一個“Version”副標題 | @version version-text |
3. 接下來就是最後一步，生成了，說實話，我之前不使用Java Doc 的原因，很大一部分就是因為，生成命令過於複雜了。但是這次，我做了一個仔細的分析，力求可以清晰的使用，並且總結兩條常用的可以讓大家直接複製生成doc的常用命令。
單個Java檔案：
javadoc -locale zh_CN -d [apidoc] -windowtitle [title] -doctitle [doctitle] -encoding UTF-8 -charset UTF-8 *HelloWorld.java[apidoc] : 替換成希望生成的doc文件名
[title] : 替換成網頁標題
[doctitle] : 替換成文件題目
[*HelloWorld.java] : 替換成要編譯的檔案多檔案多包：
包的根目錄處新建 packagepath.txt 檔案： 內容為每個類所在的包名，這個不適用萬用字元，不會自動讀取子目錄，所以要把所有用到的全部列出來，中間使用空格隔開，沒有辦法讀取根目錄處的java檔案。 javadoc -locale zh_CN -d [apidoc] -windowtitle [title] -doctitle [doctitle] -encoding UTF-8 -charset UTF-8 @packagepath.txt或者直接：
javadoc -locale zh_CN -author -version -d [apidoc] -windowtitle [title] -doctitle [doctitle] -encoding UTF-8 -charset UTF-8 @packagepath.txt[apidoc] : 替換成希望生成的doc文件名
[title] : 替換成網頁標題
[doctitle] : 替換成文件題目
[*HelloWorld.java] : 替換成要編譯的檔案想要包含版本號和作者的話，在 -locale zh_CN 後新增 -author -version
javadoc -locale zh_CN -author -version -d [apidoc] -windowtitle [title] -doctitle [doctitle] -encoding UTF-8 -charset UTF-8 包名1 包名2 包名3
4. 詳細的命令使用，有心研究的可以看一下
javadoc -help
用法：javadoc [選項] [軟體包名稱] [原始檔] [@file]
-overview <檔案> 讀取 HTML 檔案的概述文件
-public 僅顯示公共類和成員
-protected 顯示受保護/公共類和成員（預設）
-package 顯示軟體包/受保護/公共類和成員
-private 顯示所有類和成員
-help 顯示命令列選項並退出
-doclet <類> 通過替代 doclet 生成輸出
-docletpath <路徑> 指定查詢 doclet 類檔案的位置
-sourcepath <路徑列表> 指定查詢原始檔的位置
-classpath <路徑列表> 指定查詢使用者類檔案的位置
-exclude <軟體包列表> 指定要排除的軟體包的列表
-subpackages <子軟體包列表> 指定要遞迴裝入的子軟體包
-breakiterator 使用 BreakIterator 計算第 1 句
-bootclasspath <路徑列表> 覆蓋引導類載入器所裝入的
類檔案的位置
-source <版本> 提供與指定版本的源相容性
-extdirs <目錄列表> 覆蓋安裝的擴充套件目錄的位置
-verbose 輸出有關 Javadoc 正在執行的操作的訊息
-locale <名稱> 要使用的語言環境，例如 en_US 或 en_US_WIN
-encoding <名稱> 原始檔編碼名稱
-quiet 不顯示狀態訊息
-J<標誌> 直接將 <標誌> 傳遞給執行時系統
通過標準 doclet 提供：
-d <目錄> 輸出檔案的目標目錄
-use 建立類和軟體包用法頁面
-version 包含 @version 段
-author 包含 @author 段
-docfilessubdirs 遞迴複製文件檔案子目錄
-splitindex 將索引分為每個字母對應一個檔案
-windowtitle <文字> 文件的瀏覽器視窗標題
-doctitle <html 程式碼> 包含概述頁面的標題
-header <html 程式碼> 包含每個頁面的頁首文字
-footer <html 程式碼> 包含每個頁面的頁尾文字
-bottom <html 程式碼> 包含每個頁面的底部文字
-link <url> 建立指向位於 <url> 的 javadoc 輸出的連結
-linkoffline <url> <url2> 利用位於 <url2> 的軟體包列表連結至位於 <url>
的文件
-excludedocfilessubdir <名稱 1>:..排除帶有給定名稱的所有文件檔案子目錄。
-group <名稱> <p1>:<p2>.. 在概述頁面中，將指定的軟體包分組
-nocomment 抑止描述和標記，只生成宣告。
-nodeprecated 不包含 @deprecated 資訊
-noqualifier <名稱 1>:<名稱 2>:...從輸出中排除限定符的列表。
-nosince 不包含 @since 資訊
-notimestamp 不包含隱藏時間戳
-nodeprecatedlist 不生成已過時的列表
-notree 不生成類分層結構
-noindex 不生成索引
-nohelp 不生成幫助連結
-nonavbar 不生成導航欄
-serialwarn 生成有關 @serial 標記的警告
-tag <名稱>:<位置>:<標題> 指定單個變數自定義標記
-taglet 要註冊的 Taglet 的全限定名稱
-tagletpath Taglet 的路徑
-charset <字符集> 用於跨平臺檢視生成的文件的字符集。
-helpfile <檔案> 包含幫助連結所連結到的檔案
-linksource 以 HTML 格式生成源
-sourcetab <製表符長度> 指定源中每個製表符佔據的空格數
-keywords 使軟體包、類和成員資訊附帶 HTML 元標記
-stylesheetfile <路徑> 用於更改生成文件的樣式的檔案
-docencoding <名稱> 輸出編碼名稱
5. 最後放上一個超簡單的命令，但是貌似很容易出問題：
javadoc AddNum.java
如果你正在使用 JDK 1.7 那麼 Javadoc 不會生成 stysheet.css，所以我建議直接下載一份，然後放進生成的index.html同級目錄即可：右鍵連結另存為