JavaDoc文檔生成

概要描述

生成javaDoc方式

介紹

所有的Javadoc註釋以/*開始，以/結束，每個註釋包含一些描述性的文本及若干個Javadoc標籤。描述性的文本不但可以用平面文本，還可以使用HTML文本；Javadoc標籤一般以"@“爲前綴，有的也以”{@“爲前綴，以”}"結束，如{@value }。

JavaDoc標籤

標籤	描述	示例
@author	標識一個類的作者	@author description
@deprecated	指名一個過期的類或成員	@deprecated description
{@docRoot}	指明當前文檔根目錄的路徑	Directory Path
@exception	標誌一個類拋出的異常	@exception exception-name explanation
{@inheritDoc}	從直接父類繼承的註釋	Inherits a comment from the immediate surperclass.
{@link}	插入一個到另一個主題的鏈接	{@link name text}
{@linkplain}	插入一個到另一個主題的鏈接，但是該鏈接顯示純文本字體	Inserts an in-line link to another topic.
@param	說明一個方法的參數	@param parameter-name explanation
@return	說明返回值類型	@return explanation
@see	指定一個到另一個主題的鏈接	@see anchor
@serial	說明一個序列化屬性	@serial description
@serialData	說明通過writeObject( ) 和 writeExternal( )方法寫的數據	@serialData description
@serialField	說明一個ObjectStreamField組件	@serialField name type description
@since	標記當引入一個特定的變化時	@since release
@throws	和 @exception標籤一樣.	The @throws tag has the same meaning as the @exception tag.
{@value}	顯示常量的值，該常量必須是static屬性。	Displays the value of a constant, which must be a static field.
@version	指定類的版本	@version info

標記位置限制：

標記	範圍
@see、@deprecated、@author、@version	類或者接口文檔註釋
@see、@deprecated、@param、@return、@throws、@exception	方法或者構造器文檔註釋
@see、@deprecated	文檔註釋

標籤詳細介紹

概要描述

@see

可以通過這個標籤在當前點鏈接到某個類、值域或方法的說明上。爲了鏈接到當前類的值域或方法上，在值域和方法名前必須帶一個#號，如：
@see #getSex() 鏈接方法
@see #MALE 鏈接值域
@see javadoc.tool.Car 鏈接類
@see javadoc.tool.Car#drive(int,int)：鏈接到drive(int direction,int speed)
@see javadoc.tool.Car#drive(int)：鏈接到drive(int speed)

@link

@link：{@link 包名.類名#方法名(參數類型)} 用於快速鏈接到相關代碼
@link的@see很相似，唯一不同的是它可以嵌套在註釋的描述文本中，在生成Javadoc文檔時轉換成一個關聯鏈接。如：

@param sex int 性別，有效值是{@link #MALE }和{@link #FEMALE}
@see javadoc.tool.Car#drive(int)

@code

@code： {@code text} 將文本標記爲code
一般在Javadoc中只要涉及到類名或者方法名，都需要使用@code進行標記。
將文本標記爲代碼樣式的文本，在code內部可以使用 < 、> 等不會被解釋成html標籤, code標籤有自己的樣式

@param

一般類中支持泛型時會通過@param來解釋泛型的類型
@param <E> the type of elements in this list

@author

詳細描述後面一般使用@author來標記作者，如果一個文件有多個作者來維護就標記多個@author，@author 後面可以跟作者姓名(也可以附帶郵箱地址)、組織名稱(也可以附帶組織官網地址)
@author Rod Johnson
@author Igor Hersht, [email protected]
@author <a href=“mailto:[email protected]” >Ovidiu Predescu</a>

@since

@since 一般用於標記文件創建時項目當時對應的版本，一般後面跟版本號，也可以跟是一個時間，表示文件當前創建的時間,從以下版本開始
@since JDK1.8

@return

@return 跟返回值的描述
@return {@code true} if the {@code String} is not {@code null}, its

@throws

@throws 跟異常類型異常描述 , 用於描述方法內部可能拋出的異常
@throws IllegalArgumentException when the given source contains invalid encoded sequences

@exception

用於描述方法簽名throws對應的異常
@exception IllegalArgumentException if key is null.

@value

用於標註在常量上，{@value} 用於表示常量的值
默認數量 {@value}
private static final Integer QUANTITY = 1;

@inheritDoc

@inheritDoc用於註解在重寫方法或者子類上，用於繼承父類中的Javadoc

基類的文檔註釋被繼承到了子類
子類可以再加入自己的註釋（特殊化擴展）
@return @param @throws 也會被繼承

生成javaDoc方式

指定編碼選項 -encoding utf-8

使用CMD生成註釋文檔

可以利用Javadoc工具將Java源代碼中的文檔註釋自動轉化成API文檔。

-d(directory):該選項指定一個路徑，用於將生成的API文檔放到指定目錄下。
-windowtitle(text):該選項指定一個字符串，用於設置API文檔的瀏覽器窗口標題。
-doctitle(html-code):該選項指定一個HTML格式的文本，用於指定概述頁面的標題。
注意：只有對處於多個包下的源文件來生成API文檔時，纔有概述頁面。
-header(html-code):該選項指定一個HTML格式的文本，包含每個頁面的頁眉。
除此之外，javadoc命令還包含了大量其他選項，我們可以通過在命令行窗口執行javadoc -help命令來查看javadoc命令的所有選項。`

javadoc -encoding utf-8 Fish.java javaDoc文檔生成在cmd當前文件夾下，一般指定路徑

命令：

D:\work\Java\jdk1.8.0_144\bin\javadoc.exe -encoding utf-8 -d E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\ E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java

D:\work\Java\jdk1.8.0_144\bin\javadoc.exe //表示javadoc.exe 位置
-encoding utf-8 //參數設置字符utf-8
-d E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\ //生成註釋文檔保存的文件
E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java //要查詢的源碼入口

C:\Users\bellus>D:\work\Java\jdk1.8.0_144\bin\javadoc.exe -encoding utf-8 -d E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\  E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java
正在加載源文件E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java...
正在構造 Javadoc 信息...
E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java:3: 錯誤: 程序包org.springframework.boot不存在
import org.springframework.boot.SpringApplication;
                               ^
E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java:4: 錯誤: 程序包org.springframework.boot.autoconfigure不存在
import org.springframework.boot.autoconfigure.SpringBootApplication;
                                             ^
E:\AllWorkspace\eclipse_mars_workspace\springboot\src\main\java\com\lushunde\springboot\Application.java:6: 錯誤: 找不到符號
@SpringBootApplication
 ^
  符號: 類 SpringBootApplication
正在創建目標目錄: "E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\"
標準 Doclet 版本 1.8.0_144
正在構建所有程序包和類的樹...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\com\lushunde\springboot\Application.html...
javadoc: 警告 - 找不到類SpringBootApplication。
javadoc: 警告 - 找不到類SpringBootApplication。
javadoc: 警告 - 找不到類SpringBootApplication。
javadoc: 警告 - 找不到類SpringBootApplication。
javadoc: 警告 - 找不到類SpringBootApplication。
javadoc: 警告 - 找不到類SpringBootApplication。
javadoc: 警告 - 找不到類SpringBootApplication。
javadoc: 警告 - 找不到類SpringBootApplication。
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\com\lushunde\springboot\package-frame.html...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\com\lushunde\springboot\package-summary.html...
javadoc: 警告 - 找不到類SpringBootApplication。
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\com\lushunde\springboot\package-tree.html...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\constant-values.html...
正在構建所有程序包和類的索引...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\overview-tree.html...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\index-all.html...
javadoc: 警告 - 找不到類SpringBootApplication。
javadoc: 警告 - 找不到類SpringBootApplication。
javadoc: 警告 - 找不到類SpringBootApplication。
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\deprecated-list.html...
javadoc: 警告 - 找不到類SpringBootApplication。
正在構建所有類的索引...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\allclasses-frame.html...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\allclasses-noframe.html...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\index.html...
正在生成E:\AllWorkspace\eclipse_mars_workspace\springboot\doc\help-doc.html...
16 個警告

C:\Users\bellus>

使用eclipse生成註釋文檔

eclipse -> 選中項目右鍵 -> Export -> java -> javadoc -> Next

配置javadoc.exe執行文件目錄，要生成的項目，文檔生成目錄

可忽略或者默認

設置編碼和jdk版本

完成。

JavaDoc使用和文檔生成