(JDK)[建立和構建應用程序的主要工具] 之 javadoc

時間 2019-11-07

標籤 jdk 建立構建應用程序主要工具 javadoc 欄目 Java 简体版

原文原文鏈接

1. 簡述

該的Javadoc ™工具解析聲明和文檔註釋一組Java源文件並生成對應的一組描述（默認）的HTML頁面的公有和受保護類，嵌套類（但不是匿名內部類），接口，構造，方法和領域。您能夠使用它來生成API（應用程序編程接口）文檔或一組源文件的實現文檔。您能夠在整個包，單個源文件或二者上運行Javadoc工具。記錄整個包時，您能夠使用-subpackages 從頂級目錄遞歸遍歷，或者傳遞明確的包名列表。記錄單個源文件時，會傳入source（.java）文件名列表。示例在本文檔的末尾給出。接下來介紹Javadoc如何處理源文件。html

2. 命令用法

用法: javadoc [options] [packagenames] [sourcefiles] [@files]
  -overview <file>                 從 HTML 文件讀取概覽文檔
  -public                          僅顯示 public 類和成員
  -protected                       顯示 protected/public 類和成員 (默認值)
  -package                         顯示 package/protected/public 類和成員
  -private                         顯示全部類和成員
  -help                            顯示命令行選項並退出
  -doclet <class>                  經過替代 doclet 生成輸出
  -docletpath <path>               指定查找 doclet 類文件的位置
  -sourcepath <pathlist>           指定查找源文件的位置
  -classpath <pathlist>            指定查找用戶類文件的位置
  -cp <pathlist>                   指定查找用戶類文件的位置
  -exclude <pkglist>               指定要排除的程序包列表
  -subpackages <subpkglist>        指定要遞歸加載的子程序包
  -breakiterator                   計算帶有 BreakIterator 的第一個語句
  -bootclasspath <pathlist>        覆蓋由引導類加載器所加載的
                                   類文件的位置
  -source <release>                提供與指定發行版的源兼容性
  -extdirs <dirlist>               覆蓋所安裝擴展的位置
  -verbose                         輸出有關 Javadoc 正在執行的操做的信息
  -locale <name>                   要使用的區域設置, 例如 en_US 或 en_US_WIN
  -encoding <name>                 源文件編碼名稱
  -quiet                           不顯示狀態消息
  -J<flag>                         直接將 <flag> 傳遞到運行時系統
  -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>                      建立指向位於 <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>              指定輸出的字符編碼
複製代碼

eg:java

javadoc -encoding UTF-8 -charset UTF-8 TestJavaDoc.java

正在加載源文件TestJavaDoc.java...
正在構造 Javadoc 信息...
標準 Doclet 版本 1.8.0_161
正在構建全部程序包和類的樹...
正在生成./TestJavaDoc.html...
正在生成./package-frame.html...
正在生成./package-summary.html...
正在生成./package-tree.html...
正在生成./constant-values.html...
正在構建全部程序包和類的索引...
正在生成./overview-tree.html...
正在生成./index-all.html...
正在生成./deprecated-list.html...
正在構建全部類的索引...
正在生成./allclasses-frame.html...
正在生成./allclasses-noframe.html...
正在生成./index.html...
正在生成./help-doc.html...
複製代碼

3. 主要標記簡介

3.1 @see

參考。添加「另請參見」標題，其中包含指向引用的連接/文本條目/參考類。文檔註釋能夠包含任意數量的 @see標記，這些標記都分組在同一標題下。此標記在任何文檔註釋中都有效：概述，包，類，接口，構造函數，方法或字段。要將句子中的內嵌連接插入包，類或成員，請參閱{@link}。如下是@see三種最多見的使用node

3.1.1 @see "字符串"

添加字符串的文本條目。沒有生成連接。該字符串是書籍或其餘對URL不可用的信息的引用。Javadoc工具經過查找double-quote（"）做爲第一個字符來區別於之前的狀況。eg：web

@see「Java編程語言」
複製代碼

3.1.2 @see <a href="URL＃值">標籤 </a>

加URL＃value定義的連接。該 URL＃值是相對或絕對URL。Javadoc工具經過查找小於號（<）做爲第一個字符來區別於其餘狀況。eg：spring

@see <a href="https//blog.catalpaflat.cn/"> CatalpaFlat </a>
複製代碼

3.1.3 @see package.class #成員標籤

用於標明參考某個類或某個類的成員（字段/方法/構造函數等）編程

eg：瀏覽器

引用當前類
@see  #字段
@see  #方法（Type，Type，...）
@see  #方法的成員（類型argname，類型argname，...）
@see  #構造函數（Type，Type，...）
@see  #構造函數（類型argname，類型argname，.. 。）

引用當前或導入的包中的另外一個類
@see  Class #字段
@see  Class #方法（Type，Type，...）
@see  類#方法（類型argname，Type argname，...）
@see  類#構造函數（Type，Type，...）
@see  類#構造函數（類型argname，類型argname，...）
@see  Class.NestedClass 
@see  類

引用另外一個包中的元素（徹底限定）
@see  package.Class #字段
@see  package.Class #方法（Type，Type，...）
@see  package.Class #方法（類型argname，類型argname，...）
@see  package.Class #構造函數（Type，Type，...）
@see  package.Class #構造函數（類型argname，Type argname，...）
@see  package.Class.NestedClass 
@see  package.Class
@see  package
複製代碼

3.2 @author

使用-author選項時，將「Author」條目與指定的name-text一塊兒添加到生成的文檔中。文檔註釋可能包含多個@author標記。您能夠爲每一個@author標記指定一個名稱或爲每一個標記指定多個名稱在前一種狀況下，Javadoc工具,在名稱之間插入逗號（）和空格。在後一種狀況下，只需將整個文本複製到生成的文檔而不進行解析。所以，若是須要除逗號以外的本地化名稱分隔符，則能夠每行使用多個名稱。bash

eg:app

@author CatalpaFlat
複製代碼

3.3 @version

@version標記的參數的Java軟件約定是SCCS字符串「％I％，％G％」，1.39, 02/28/97當從SCCS中檢出文件時，它轉換爲相似「」（mm / dd / yy）的內容。less

文檔註釋可能包含多個@version標記。若是有意義，您能夠爲每一個@version標記指定一個版本號，或爲每一個標記指定多個版本號。在前一種狀況下，Javadoc工具,在名稱之間插入逗號（）和空格。在後一種狀況下，只需將整個文本複製到生成的文檔而不進行解析。所以，若是須要除逗號以外的本地化名稱分隔符，則能夠每行使用多個名稱。

eg:

@version 1.0.0, 13 Dec 2014
複製代碼

3.4 {@link}

格式：{@link package.class #成員標籤}
插入內容：插入帶有可見文本標籤的內嵌連接，該連接指向引用類的指定包、類或成員名稱的文檔。
此標記在全部文檔註釋中都有效：概述，包，類，接口，構造函數，方法和字段，包括任何標記的文本部分（eg: @return，@ param和@deprecated）。
和@see的區別：二者都須要相同的引用，而且接受{package.class #成員和標籤}徹底相同的語法。主要區別在於 {@link}生成內聯連接而不是將連接放在「另請參見」部分。此外，{@link} 標記以花括號開頭和結尾，以將其與內嵌文本的其他部分分開。若是您須要在標籤內使用「}」，請使用HTML實體表示法＆＃125;
{@link}句子中容許的標籤數量沒有限制。您能夠在任何文檔註釋的主要描述部分或任何標記的文本部分（eg: @deprecated，@return或@param）中使用此標記。

eg:

// 引用getComponentAt(int, int)該方法的註釋
Use the {@link #getComponentAt(int, int) getComponentAt} method.
複製代碼

3.5 {@value}

3.5.1 在{@value}靜態字段的doc註釋中使用（無任何參數）時，它顯示該常量的值：

/** * The value of this constant is {@value}. */
public static final String SCRIPT_START = "<script>"
複製代碼

3.5.2 當在任何doc註釋中與參數package.class #field一塊兒使用時，它會顯示指定常量的值：

/** * Evaluates the script starting with {@value #SCRIPT_START}. */
public String evalScript(String script) {
}

複製代碼

3.6 @param

參數名稱描述。

將具備指定參數名稱的參數後跟指定描述添加到「參數」部分。在編寫文檔註釋時，能夠將描述繼續到多行。此標記僅在方法，構造函數或類的doc註釋中有效。參數名稱能夠是方法或構造函數中的參數名稱，也能夠是類，方法或構造函數的類型參數的名稱。在此參數名稱周圍使用尖括號指定使用類型參數。

eg:

//類範型
 /** * @param <E> Type of element stored in a list */
 public interface List<E> extends Collection<E> {
 }


//方法上
/** * @param string the string to be converted * @param type the type to convert the string to * @param <T> the type of the element * @param <V> the value of the element */
 <T, V extends T> V convert(String string, Class<T> type) {
 }
複製代碼

3.7 @return

添加帶有描述文本的「返回」部分。該文本應描述返回類型和容許的值範圍。此標記僅在方法的doc註釋中有效。有關更多詳細信息，請參閱編寫@return標記。

eg:

/** * * @return String */
private String obtain(){
    return "CatalpaFlat";
}
複製代碼

3.8 @throws、@exception

在@throws和@exception標籤是同義詞。使用類名和描述文本向生成的文檔添加「throw」子標題。類名是可經過該方法拋出的異常的名稱。此標記僅在方法或構造函數的doc註釋中有效。若是未徹底指定此類，則Javadoc工具使用搜索順序查找此類。@throws對於相同或不一樣的例外，能夠在給定的doc註釋中使用多個標籤。

爲了確保記錄全部已檢查的異常，若是 @throwsthrows子句中的異常不存在標記，則Javadoc工具會自動將該異常添加到HTML輸出（沒有描述），就像使用@throws標記記錄同樣。

@throws僅當在重寫方法中顯式聲明異常時，纔會將文檔從重寫方法複製到子類。從接口方法複製到實現方法也是如此。您能夠使用{@inheritDoc}強制@throws繼承文檔。

3.9 {@inheritDoc}

將文檔從「copies」可繼承類或可實現的接口繼承（複製）到此標記位置的當前doc註釋中。這容許您在繼承樹的更高位置編寫更多通用註釋，並在複製的文本週圍編寫。此標記僅在文檔註釋中的這些位置有效：

在方法的主要描述塊中。在這種狀況下，主要描述從層次結構中的類或接口複製。
在方法的@return，@ param和@throws標籤的文本參數中。在這種狀況下，標記文本將從層次結構中的相應標記複製。

有關如何在繼承層次結構中找到註釋的更準確說明，請參見自動複製方法註釋。請注意，若是缺乏此標記，則根據該部分中描述的規則自動繼承註釋。

4. 各文檔註釋

4.1 包文檔標籤

描述： 包標籤是能夠出如今包的文檔註釋中的標籤（位於名爲package.htmlor 的源文件中 package-info.java）。該 @serial標籤只能用這裏使用 include或exclude說法。

可用標籤🏷️：

包標籤	描述
@see	參考
@since	since-text（用於當前項目版本）
@serial	描述
@author	做者
@version	版本
{@link}	入帶有可見文本標籤的內嵌連接，該連接指向引用類的指定包，類或成員名稱的文檔。
{@linkplain}	{@link}與連接標籤相同，除了代碼字體外，以純文本顯示。標籤是純文本時頗有用
{@docRoot}	表示從任何生成的頁面生成的文檔（目標）根目錄的相對路徑（版權標明）

結構：

該包的簡要功能描述
該包的詳細描述（@link /@code）
新建該包時當前項目的版本 @since
做者 @author
參考現有類 @see

eg：

/** * Provides the classes necessary to create an * applet and the classes an applet uses * to communicate with its applet context. * <p> * The applet framework involves two entities: * the applet and the applet context. * An applet is an embeddable window (see the * {@link java.awt.Panel} class) with a few extra * methods that the applet context can use to * initialize, start, and stop the applet. * * @since 1.0 * @see java.awt */
package java.lang.applet;
複製代碼

4.2 類和接口文檔標記

可用標籤🏷️：

包標籤	描述
@see	參考
@since	since-text（用於當前項目版本）
@serial	描述
@deprecated	設置過時
@author	做者
@version	版本
{@link}	入帶有可見文本標籤的內嵌連接，該連接指向引用類的指定包，類或成員名稱的文檔。
{@linkplain}	{@link}與連接標籤相同，除了代碼字體外，以純文本顯示。標籤是純文本時頗有用
{@docRoot}	表示從任何生成的頁面生成的文檔（目標）根目錄的相對路徑（版權標明）

結構：

該類的簡要功能描述
該類的詳細描述
做者 @author
撰寫該類時類版本 @version
撰寫該類時當前項目的版本 @since
參考現有類 @see

eg:

/** * A class representing a window on the screen. * For example: * <pre> * Window win = new Window(parent); * win.show(); * </pre> * * @author CatalpaFlat * @version 1.15, 13 Dec 2006 * @see java.awt.BaseWindow * @see java.awt.Button */
class Window extends BaseWindow {
   ...
}
複製代碼

4.3 字段文檔標籤

可用標籤🏷️：

包標籤	描述
@see	參考
@since	since-text（用於當前項目版本）
@deprecated	設置過時
@serial	描述
@serialField	字段類型/字段描述
{@link}	入帶有可見文本標籤的內嵌連接，該連接指向引用類的指定包，類或成員名稱的文檔。
{@linkplain}	{@link}與連接標籤相同，除了代碼字體外，以純文本顯示。標籤是純文本時頗有用
{@docRoot}	表示從任何生成的頁面生成的文檔（目標）根目錄的相對路徑（版權標明）
{@value}	常量的值

結構：

描述 {@link} / {@linkplain}
@serial/ @serialField
{@value}
{@docRoot}
@see

eg:

/** * The X-coordinate of the component. * * @see #getLocation() */
int x = 1263732;
複製代碼

4.4 構造函數和方法文檔標記

除了 @return它們不能出如今構造函數中，而且 {@inheritDoc}具備某些限制。該@serialData標籤只能用於文檔註釋中使用某些序列化方法。

可用標籤🏷️：

包標籤	描述
@see	參考
@since	since-text（用於當前項目版本）
@param	參數信息
@return	返回信息
@deprecated	設置過時
@throws 和 @exception	異常
@serialData
{@link}	入帶有可見文本標籤的內嵌連接，該連接指向引用類的指定包，類或成員名稱的文檔。
{@linkplain}	{@link}與連接標籤相同，除了代碼字體外，以純文本顯示。標籤是純文本時頗有用
{@docRoot}	表示從任何生成的頁面生成的文檔（目標）根目錄的相對路徑（版權標明）
{@inheritDoc}	繼承父級的註釋標籤

eg:

/** * Returns the character at the specified index. An index * ranges from <code>0</code> to <code>length() - 1</code>. * * @param index the index of the desired character. * @return the desired character. * @exception StringIndexOutOfRangeException * if the index is not in the range <code>0</code> * to <code>length()-1</code>. * @see java.lang.Character#charValue() */
public char charAt(int index) {
   ...
}
複製代碼

5. 示例

/** * Represents an HTTP request or response entity, consisting of headers and body. * * <p>Typically used in combination with the {@link org.springframework.web.client.RestTemplate}, * like so: * <pre class="code"> * HttpHeaders headers = new HttpHeaders(); * headers.setContentType(MediaType.TEXT_PLAIN); * HttpEntity&lt;String&gt; entity = new HttpEntity&lt;String&gt;(helloWorld, headers); * URI location = template.postForLocation("http://example.com", entity); * </pre> * or * <pre class="code"> * HttpEntity&lt;String&gt; entity = template.getForEntity("http://example.com", String.class); * String body = entity.getBody(); * MediaType contentType = entity.getHeaders().getContentType(); * </pre> * Can also be used in Spring MVC, as a return value from a @Controller method: * <pre class="code"> * &#64;RequestMapping("/handle") * public HttpEntity&lt;String&gt; handle() { * HttpHeaders responseHeaders = new HttpHeaders(); * responseHeaders.set("MyResponseHeader", "MyValue"); * return new HttpEntity&lt;String&gt;("Hello World", responseHeaders); * } * </pre> * * @author Arjen Poutsma * @author Juergen Hoeller * @since 3.0.2 * @see org.springframework.web.client.RestTemplate * @see #getBody() * @see #getHeaders() */
public class HttpEntity<T> {

	/** * The empty {@code HttpEntity}, with no body or headers. */
	public static final HttpEntity<?> EMPTY = new HttpEntity<>();
	
	/** * Create a new, empty {@code HttpEntity}. */
	protected HttpEntity() {
		this(null, null);
	}
	
	/** * Create a new {@code HttpEntity} with the given headers and no body. * @param headers the entity headers */
	public HttpEntity(MultiValueMap<String, String> headers) {
		this(null, headers);
	}
	/** * Returns the body of this entity. */
	@Nullable
	public T getBody() {
		return this.body;
	}

	/** * Indicates whether this entity has a body. */
	public boolean hasBody() {
		return (this.body != null);
	}


	@Override
	public boolean equals(@Nullable Object other) {
		if (this == other) {
			return true;
		}
		if (other == null || other.getClass() != getClass()) {
			return false;
		}
		HttpEntity<?> otherEntity = (HttpEntity<?>) other;
		return (ObjectUtils.nullSafeEquals(this.headers, otherEntity.headers) &&
				ObjectUtils.nullSafeEquals(this.body, otherEntity.body));
	}
}
複製代碼