Javadoc生成的詳細操作教程

所有知識體系文章，GitHub已收錄，歡迎Star！

GitHub地址： https://github.com/Ziphtracks/JavaLearningmanual

搜索關注微信公衆號“碼出Offer”，Z哥送你學習福利資源！

Javadoc文檔

一、什麼是Javadoc文檔

javadoc是Sun公司提供的一個技術，它從程序源代碼中抽取類、方法、成員等註釋形成一個和源代碼配套的API幫助文檔。也就是說，只要在編寫程序時以一套特定的標籤作註釋，在程序編寫完成後，通過Javadoc就可以同時形成程序的開發文檔了。

javadoc命令是用來生成自己API文檔的，使用方式：使用命令行在目標文件所在目錄輸入javadoc +文件名.java。

二、Javadoc文檔註釋

Java註釋分類：

• //註釋內容：單行註釋，不支持換行
• /*註釋內容*/：多行註釋，支持換行
• Javadoc文檔註釋格式如下，支持換行，可以生成Javadoc文檔【重點】

/**
 * 文檔註釋
 */

三、常用註釋文檔標記

參考官方文檔： javadoc - The Java API Documentation Generator

常用標籤	說明
@author 作者	作者標識
@version 版本號	版本號
@param 參數名 描述	方法的入參名及描述信息，如入參有特別要求，可在此註釋。
@return 描述	對函數返回值的註釋
@deprecated 過期文本	標識隨着程序版本的提升，當前API已經過期，僅爲了保證兼容性依然存在，以此告之開發者不應再用這個API。
@throws異常類名	構造函數或方法所會拋出的異常。
@exception 異常類名	同@throws。
@see 引用	查看相關內容，如類、方法、變量等。
@since 描述文本	API在什麼程序的什麼版本後開發支持。
{@link包.類#成員 標籤}	鏈接到某個特定的成員對應的文檔中。
{@value}	當對常量進行註釋時，如果想將其值包含在文檔中，則通過該標籤來引用常量的值。
不常用標籤	說明
@serial	說明一個序列化屬性
@serialField	說明一個ObjectStreamField組件
@serialData	說明通過writeObject( ) 和 writeExternal( )方法寫的數據
{@docRoot}	指明當前文檔根目錄的路徑
{@inheritDoc}	從直接父類繼承的註釋
{@literal}	顯示文本而不將其解釋爲HTML標記或嵌套的javadoc標記。
{@code}	以字體 顯示文本，code而不將文本解釋爲HTML標記或嵌套的Javadoc標記。

四、Javadoc選項說明

Javadoc命令格式： javadoc [選項] [軟件包名稱] [源文件]

4.1 選項說明

選項	說明
-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<標誌>	直接將 <標誌> 傳遞給運行時系統
-X	輸出非標準選項的提要

標準doclet選項	說明
-d	<directory>輸出文件的目標目錄
-use	創建類和程序包用法頁面
-version	包含 @version 段
-author	包含 @author 段
-docfilessubdirs	遞歸複製文檔文件子目錄
-splitindex	將索引分爲每個字母對應一個文件
-windowtitle	<text>文檔的瀏覽器窗口標題
-doctitle	<html-code>包含概覽頁面的標題
-header	<html-code>包含每個頁面的頁眉文本
-footer	<html-code>包含每個頁面的頁腳文本
-top	<html-code>包含每個頁面的頂部文本
-bottom	<html-code>包含每個頁面的底部文本
-link	創建指向位於 <url> 的 javadoc 輸出的鏈接
-linkoffline	<url> <url2>利用位於 <url2> 的程序包列表鏈接至位於 <url> 的文檔
-excludedocfilessubdir	<name1>:… 排除具有給定名稱的所有文檔文件子目錄。
-group	<name> <p1>:<p2>… 在概覽頁面中, 將指定的程序包分組
-nocomment	不生成說明和標記, 只生成聲明。
-nodeprecated	不包含 @deprecated 信息
-noqualifier	<name1>:<name2>:… 輸出中不包括指定限定符的列表。
-nosince	不包含 @since 信息
-notimestamp	不包含隱藏時間戳
-nodeprecatedlist	不生成已過時的列表
-notree	不生成類分層結構
-noindex	不生成索引
-nohelp	不生成幫助鏈接
-nonavbar	不生成導航欄
-serialwarn	生成有關 @serial 標記的警告
-tag	<name>:<locations>:<header> 指定單個參數定製標記
-taglet	要註冊的 Taglet 的全限定名稱
-tagletpath	Taglet 的路徑
-charset	<charset> 用於跨平臺查看生成的文檔的字符集。
-helpfile	<file>包含幫助鏈接所鏈接到的文件
-linksource	以 HTML 格式生成源文件
-sourcetab	<tab length>指定源中每個製表符佔據的空格數
-keywords	使程序包, 類和成員信息附帶 HTML 元標記
-stylesheetfile	<path>用於更改生成文檔的樣式的文件
-docencoding	<name>指定輸出的字符編碼

4.2 標記的順序

1. @author (classes and interfaces only, required)
2. @version (classes and interfaces only, required. See footnote 1)
3. @param (methods and constructors only)
4. @return (methods only)
5. @exception (@throws is a synonym added in Javadoc 1.2)
6. @see
7. @since
8. @serial (or @serialField or @serialData)
9. @deprecated (see How and When To Deprecate APIs)

4.3 可以多次使用標記

1. @author 標記應按時間順序排列，並用逗號分隔。
2. @ param 標記應該在參數聲明的順序列出，這使它更容易在視覺上與聲明相匹配的列表。
3. @throws 標記 (類同 @exception)應按字母順序列出的例外的名字。
4. @see 標記遵循由近到遠，參數由少到多，由上到下的順序。

五、命令生成doc文檔

5.1 測試所在的目錄結構

項目所在目錄爲：d:\Code\javase\firstdoc

目錄結構如下：

創建的兩個類均有javadoc文檔註釋如下：

Calculator：

package com.mylifes1110.java;

/**
 * @author Ziph
 * @since 1.8
 * @version 1.0
 */
public class Calculator {
    /**
     * 無參構造器
     */
    public Calculator() {
    }

    /**
     * 計算兩個數字相加
     * @param num1 整數1
     * @param num2 整數2
     * @return 兩個整數之和
     */
    public int add(int num1, int num2) {
        return num1 + num2;
    }
}

CalculatorTest：

package com.mylifes1110.test;

/**
 * @author Ziph
 * @since 1.8
 * @version 1.0
 */
public class CalculatorTest {
    /**
     * 測試
     */
    public CalculatorTest() {
    }
}

5.2 命令生成Javadoc文檔步驟

生成好的Javadoc文檔index.html是文檔入口，打開後即可看見doc文檔內容。

方式一：單個或多個.java文件生成doc文檔

這裏我們生成Calculator.java的doc文檔，首先先進入到Calculator.java所在目錄，然後去此文件夾中打開DOS命令窗口，此方式生成的doc文檔是默認創建了.java文件所在的包，輸入以下命令即可：

命令格式： javadoc -d 文檔存儲目錄 -encoding utf-8 -charset utf-8 Xxx.java

參數說明：

• -d 指定API文檔的輸出目錄，默認是當前目錄。建議總是指定該參數。
• -encoding UTF-8 表示你的源代碼（含有符合 JavaDoc 標準的註釋）是基於 UTF-8 編碼的，以免處理過程中出現中文等非英語字符亂碼
• -charset UTF-8 表示在處理並生成 JavaDoc 超文本時使用的字符集也是以 UTF-8 爲編碼，目前所有瀏覽器都支持 UTF-8，這樣最具有通用性，支持中文非常好

注意： 如果此文件夾內有多個.java文件需要生成，我們可以在指定.java文件的時候使用*.java。這裏utf-8編碼相關是指定文檔的編碼字符集，如果與項目或系統編碼不一致可能會造成生成的doc文檔亂碼。

javadoc -d d:\Code\javase\firstdoc\doc -encoding utf-8 -charset utf-8 Calculator.java

方式二：指定源文件路徑生成doc文檔

由於方式一每次生成doc文檔都需要進入到.java文件所在目錄操作，藉此我們簡化了此操作。使用doc文檔選項生成。首先，我們這次只需要進入到項目內的第一層文件夾，在此文件夾中就可以看到src了，然後在此文件夾中打開DOS命令窗口，此方式生成的doc文檔可以用doc文檔選項來指定源文件所在生成的目錄的包，輸入以下命令即可：

命令格式： javadoc -d 文檔存儲目錄 -encoding utf-8 charset utf-8 -sourcepath 源文件所在目錄 -subpackages 需要生成的源文件目錄包 -version -author

參數說明：

• -d 指定API文檔的輸出目錄，默認是當前目錄。建議總是指定該參數。
• -encoding UTF-8 表示你的源代碼（含有符合 JavaDoc 標準的註釋）是基於 UTF-8 編碼的，以免處理過程中出現中文等非英語字符亂碼
• -charset UTF-8 表示在處理並生成 JavaDoc 超文本時使用的字符集也是以 UTF-8 爲編碼，目前所有瀏覽器都支持 UTF-8，這樣最具有通用性，支持中文非常好
• -sourcepath 指定源代碼路徑，默認是當前目錄。 此參數通常是必須的。
• -subpackages 以遞歸的方式處理各子包。如果不使用本參數，每次只能處理一個子包（或需手工列出所有子包）。
• -author 可以將作者信息（@author ***）導出到最終生成的API文檔中。
• -version 可以生成版本信息。
• -windowtitle 設置API文檔的瀏覽器窗口標題。
• -doctitle 指定概述頁面的標題。
• -header 指定頁面的頁眉。

javadoc -d ./doc -encoding utf-8 -charset utf-8 -sourcepath d:\Code\javase\firstdoc\src -subpackages com.mylifes1110.test -version -author

查看生成的doc目錄

六、IDEA生成doc目錄

1. 首先，打開IDEA，並找到Tools -> Generate JavaDoc...

2. 生成Doc文檔中的選項操作

Loacle： 這是一個可選項，表示的是需要生成的 JavaDoc 以何種語言版本展示，根據 javadoc.exe 的幫助說明，這其實對應的就是 javadoc.exe 的 -locale 參數，如果不填，默認可能是英文或者是當前操作系統的語言。但是我們也可以填zh_CN。

3. IDEA生成Doc文檔過程

4. 查看生成後的Doc文檔