一.javadoc
1.簡述
對於Java語言，最體貼的一項設計就是它並沒有打算讓人們為了寫程序而寫程序——人們也需要考慮程序的文檔化問題。對於程序的文檔化，最大的問題 莫過於對文檔的維護。若文檔與代碼分離，那么每次改變代碼后都要改變文檔，這無疑會變成相當麻煩的一件事情。解決的方法看起來似乎很簡單：將代碼同文檔 “鏈接”起來。為達到這個目的，最簡單的方法是將所有內容都置於同一個文件。然而，為使一切都整齊划一，還必須使用一種特殊的注釋語法，以便標記出特殊的 文檔；另外還需要一個工具，用於提取這些注釋，並按有價值的形式將其展現出來。這些都是Java必須做到的。
用於提取注釋的工具叫作javadoc。它采用了部分來自Java編譯器的技術，查找我們置入程序的特殊注釋標記。它不僅提取由這些標記指示的信息，也將毗鄰注釋的類名或方法名提取出來。這樣一來，我們就可用最輕的工作量，生成十分專業的程序文檔。
javadoc輸出的是一個HTML文件，可用自己的Web瀏覽器查看。該工具允許我們創建和管理單個源文件，並生動生成有用的文檔。由於有了jvadoc，所以我們能夠用標准的方法創建文檔。而且由於它非常方便，所以我們能輕松獲得所有Java庫的文檔。
2 具體語法
所 有javadoc命令都只能出現於“/**”注釋中。但和平常一樣，注釋結束於一個“*/”。主要通過兩種方式來使用javadoc：嵌入的HTML，或 使用“文檔標記”。其中，“文檔標記”（Doc tags）是一些以“@”開頭的命令，置於注釋行的起始處（但前導的“*”會被忽略）。
有三種類型的注釋文檔，它們對應於位於注釋后面的元素：類、變量或者方法。也就是說，一個類注釋正好位於一個類定義之前；變量注釋正好位於變量定義之前；而一個方法定義正好位於一個方法定義的前面。如下面這個簡單的例子所示：
/** 一個類注釋 */
public class docTest {
/** 一個變量注釋 */
public int i;
/** 一個方法注釋 */
public void f() {}
}
注 意javadoc只能為public（公共）和protected（受保護）成員處理注釋文檔。“private”（私有）和“友好”（詳見5章）成員的 注釋會被忽略，我們看不到任何輸出（也可以用-private標記包括private成員）。這樣做是有道理的，因為只有public和 protected成員才可在文件之外使用，這是客戶程序員的希望。然而，所有類注釋都會包含到輸出結果里。
上述代碼的輸出是一個HTML文件，它與其他Java文檔具有相同的標准格式。因此，用戶會非常熟悉這種格式，可在您設計的類中方便地“漫游”。設計程序時，請務必考慮輸入上述代碼，用javadoc處理一下，觀看最終HTML文件的效果如何。
3 嵌入HTML
javadoc將HTML命令傳遞給最終生成的HTML文檔。這便使我們能夠充分利用HTML的巨大威力。當然，我們的最終動機是格式化代碼，不是為了嘩眾取寵。
注意 ：
在文檔注釋中，位於一行最開頭的星號會被javadoc丟棄。同時丟棄的還有前導空格。
javadoc會對所有內容進行格式化，使其與標准的文檔外觀相符。
不要將 標題當作嵌入HTML使用，因為javadoc會插入自己的標題，我們給出的標題會與之沖撞。
所有類型的注釋文檔——類、變量和方法——都支持嵌入HTML。
二.文件輸出
詳見：https://www.cnblogs.com/lukelook/p/11105114.html
三.@標簽使用詳解
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 info1.
1.@see 另請參閱
@see 一般用於標記該類相關聯的類,@see即可以用在類上，也可以用在方法上（#methodName（））。
/** * @see com.my.study.base.Tools * @see #name() */ public class Test { public void name() { } }
文檔顯示效果
2.@code： {@code text} 將文本標記為code
@code的使用語法{@code text} 會被解析成<code>text</code>
將文本標記為代碼樣式的文本，在code內部可以使用 < 、> 等不會被解釋成html標簽, code標簽有自己的樣式
一般在Javadoc中只要涉及到類名或者方法名，都需要使用@code進行標記。
package com.my.study.base; /** * <h1>This is a h1 demo!</h1> * {@code <h1> title h1 </h1>} * * @see com.my.study.base.Tools * @see #name() * */ public class Test { public void name() { String name = "Jim"; } }
3.@param :對參數的描述
一般類中支持泛型時會通過@param來解釋泛型的類型
/** * * @param str String value */ public void name(String str) { System.out.println(str); }
4.@author
詳細描述后面一般使用@author來標記作者，如果一個文件有多個作者來維護就標記多個@author，@author后面可以跟作者姓名(也可以附帶郵箱地址)、組織名稱(也可以附帶組織官網地址)
5.@link：{@link 包名.類名#方法名(參數類型)} 用於快速鏈接到相關代碼（一般用於描述中）
@link的使用語法{@link 包名.類名#方法名(參數類型)}，其中當包名在當前類中已經導入了包名可以省略，可以只是一個類名，也可以是僅僅是一個方法名，也可以是類名.方法名，使用此文檔標記的類或者方法，可用按住Ctrl鍵+鼠標單擊快速跳到相應的類或者方法上，解析成html其實就是使用<code>包名.類名#方法名(參數類型)</code>
/** * <h1>This is a h1 demo!</h1> * {@code <h1> title h1 </h1>} * * <P> {@link com.my.study.base.Tools} class contains many useful tools. * * @author Administrator * @author Rooker 7254478@163.com * * @see com.my.study.base.Tools * @see #name(String) * * * */
6.@since 從以下版本開始
@since 一般用於標記文件創建時項目當時對應的版本，一般后面跟版本號，也可以跟是一個時間，表示文件當前創建的時間
* @since 1.8 * @since 2020-4-29 12:32:35
7.@version 版本
@version用於標記當前版本，默認為1.0
* @version 1.0
8.@return
@return 跟返回值的描述
/** * * @param str String value * @return {@code true} if the {@code CharSequence} is not {@code null} and has length */ public Boolean name(String str) { System.out.println(str); String name = str +":"; return true ; }
9. pre結合@code使用
<pre>{@code Person[] men = people.stream() .filter(p -> p.getGender() == MALE) .toArray(Person[]::new); }</pre>
10.@throws
@throws 跟異常類型 異常描述 , 用於描述方法內部可能拋出的異常
/** * @throws IllegalArgumentException when the given source contains invalid encoded sequences */
11.@exception
@exception 用於描述方法簽名throws對應的異常
/** * @exception LoginException if the logout fails. * */ public boolean logout() throws LoginException { return false; }
12.@deprecated
@deprecated 用於標注一個類或成員已過期,通常配合{@link}使用
/** * @deprecated since 2020-2-29 13:18:58 */ public void name() { System.out.println("================="); }
13@value
{@value} 用於標注在常量上用於表示常量的值
/** 默認數量 {@value} */ private static final Integer QUANTITY = 1;
14.@inheritDoc
@inheritDoc 用於注解在重寫方法或者子類上，用於繼承父類中的Javadoc
基類的文檔注釋被繼承到了子類
子類可以再加入自己的注釋（特殊化擴展）
@return @param @throws 也會被繼承
public class SonTest extends Test { /** * {@inheritDoc} */ public Boolean name(String str) { System.out.println(str); String name = str + ":"; return false; } }
windows–>preference
Java–>Code Style–>Code Templates
code–>new Java files
編輯它
${filecomment} ${package_declaration} /** * @author 作者 E-mail: * @version 創建時間：${date} ${time} * 類說明 */ ${typecomment} ${type_declaration}
方法二：
通過菜單 Window->Preference 打開參數設置面板，然后選擇：
Java -> Code Style -> Code Templates
在右側選擇Comments,將其中的Files項，然后選右邊的”Edit”，進入編輯模式：
進入編輯模式后就可以自定義注釋了。另外可以插入一些變量，如年、日期等等。
最后，確保 Code -> New java files 中有：”${filecomment}”
當然，通過“導出”和“導入”功能，你可以把自己的模板導出來在其他機器上使用。