一、Javadoc的基本信息：
javadoc是Sun公司提供的一個技術(shù)，它從程序源代碼中抽取類、方法、成員等注釋形成一個和源代碼配套的API幫助文檔。也就是說，只要在編寫程序時以一套特定的標簽作注釋，在程序編寫完成后，通過Javadoc就可以同時形成程序的開發(fā)文檔了。javadoc命令是用來生成自己API文檔的，使用方式：使用命令行在目標文件所在目錄輸入javadoc +文件名.java。
? Javadoc主要用于代碼的注釋規(guī)范性。
Javadoc命令是用來生成自己的API文檔，使用方式：
javadoc 源文件名.java
javadoc -d 文檔存放目錄 源文件名.java
通過IDEA生成Javadoc ： Tools -> Generate JavaDoc
二、?Javadoc注釋規(guī)范?：
// 注釋一行
/ *? ? */ 注釋若干行?
/**? ……*/? 注釋若干行，寫入Javadoc文檔
如圖：
代碼：
/**
* show 方法的簡述.
* <p>show 方法的詳細說明第一行<br>
* show 方法的詳細說明第二行
* @param b true 表示顯示，false 表示隱藏
* @return 沒有返回值
*/ public void show(boolean b) {? ? frame.show(b);? ? }
三、Javadoc的基本用法
文檔格式：
?寫在類上的文檔標注一般分為三段：
第一段：概要描述，通常用一句或者一段話簡要描述該類的作用，以英文句號作為結(jié)束
第二段：詳細描述，通常用一段或者多段話來詳細描述該類的作用，一般每段話都以英文句號作為結(jié)束
第三段：文檔標注，用于標注作者、創(chuàng)建時間、參閱類等信息
生成文檔是HTML格式。
換行<br>
分段<p>(寫在段前）)
示例：
在注釋中出現(xiàn)以@開頭東東被稱之為Javadoc文檔標記，是JDK定義好的，如@author、@version、@since、@see、@link、@code、@param、@return、@exception、@throws等。? ??
主要的文檔標記
1. @link：{@link 包名.類名#方法名(參數(shù)類型)} 用于快速鏈接到相關(guān)代碼
@link的使用語法{@link 包名.類名#方法名(參數(shù)類型)}，其中當包名在當前類中已經(jīng)導入了包名可以省略，可以只是一個類名，也可以是僅僅是一個方法名，也可以是類名.方法名，使用此文檔標記的類或者方法，可用通過按住Ctrl鍵+單擊 可以快速跳到相應的類或者方法上，解析成html其實就是使用< code> 包名.類名#方法名(參數(shù)類型)< /code>
2. @code： {@code text} 將文本標記為code
{@code text} 會被解析成<code> text </code>
將文本標記為代碼樣式的文本，在code內(nèi)部可以使用 < 、> 等不會被解釋成html標簽, code標簽有自己的樣式
一般在Javadoc中只要涉及到類名或者方法名，都需要使用@code進行標記。
3. @param
一般類中支持泛型時會通過@param來解釋泛型的類型
4. @author
詳細描述后面一般使用@author來標記作者，如果一個文件有多個作者來維護就標記多個@author，@author 后面可以跟作者姓名(也可以附帶郵箱地址)、組織名稱(也可以附帶組織官網(wǎng)地址)
5. @see
@see 一般用于標記該類相關(guān)聯(lián)的類,@see即可以用在類上，也可以用在方法上。
6. @since 從以下版本開始
@since 一般用于標記文件創(chuàng)建時項目當時對應的版本，一般后面跟版本號，也可以跟是一個時間，表示文件當前創(chuàng)建的時間
7. @version 版本
@version 用于標記當前版本，默認為1.0
8. @param
@param 后面跟參數(shù)名，再跟參數(shù)描述
9. @return
@return 跟返回值的描述
10. @value
用于標注在常量上，{@value} 用于表示常量的值
此外還有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、{@code} {@value arg}幾個不常用的標簽，由于不常使用，我們不展開敘述，感興趣的讀者可以查看幫助文檔。
（1）概要描述：通常用一句或者一段話簡要描述該類的作用， 如：
如上圖利用author和version描述了該類的作者和版本
切記：當Java源代碼中包含中文字符時，我們在用javac編譯時會出現(xiàn)“錯誤：編碼GBK的不可映射字符”。
由于JDK是國際版的，我們在用javac編譯時，編譯程序首先會獲得我們操作系統(tǒng)默認采用的編碼格式（GBK），然后JDK就把Java源文件從GBK編碼格式轉(zhuǎn)換為Java內(nèi)部默認的Unicode格式放入內(nèi)存中，然后javac把轉(zhuǎn)換后的Unicode格式的文件編譯成class類文件，此時，class文件是Unicode編碼的，它暫存在內(nèi)存中，緊接著，JDK將此以Unicode格式編碼的class文件保存到操作系統(tǒng)中形成我們見到的class文件。當我們不加設(shè)置就編譯時，相當于使用了參數(shù)：javac -encoding GBK Test.java，就會出現(xiàn)不兼容的情況。
使用-encoding參數(shù)指明編碼方式：javac -encoding UTF-8 Test.java，就可以了。
當更改編碼方式為UTF-8時就可以就行生成含有中文字符的API文檔
打開生成API文檔查看剛剛定義的javadoc注釋
當然你要是定義的英文注釋就直接忽視編碼問題
最后看一下阿里巴巴的Javadoc注釋規(guī)范
阿里巴巴Java開發(fā)手冊之注釋規(guī)約：
類，類屬性、類方法的注釋必須使用Javadoc規(guī)范，使用/*內(nèi)容/格式，不得使用//XX方式。
所有的抽象方法（包括接口中的方法）必須要用Javadoc注釋，除了返回值、參數(shù)、異常說明外，還必須指出該方法做什么事情，實現(xiàn)什么功能。
所有的類都必須添加創(chuàng)建者和創(chuàng)建日期。
方法內(nèi)部的單行注釋，在被注釋語句上方另起一行，使用//注釋。方法內(nèi)部的多行注釋，使用/* */注釋，注意與代碼對齊。
所有的枚舉類型字段必須要有注釋，說明每個數(shù)據(jù)項的用途。
與其用不熟練的英文來注釋，不如用中文注釋把問題說清楚。專有名詞與關(guān)鍵字保持英文原文即可。
在修改代碼的同時，要對注釋進行相應的修改，尤其是參數(shù)，返回值，異常，核心邏輯等的修改。
謹慎注釋掉代碼。要在上方詳細說明，而不是簡單的注釋掉。如果無用，則刪除。
對于注釋的要求：
（1）能夠準確反映設(shè)計思想和代碼邏輯。
（2）能夠描述業(yè)務(wù)含義，使其他程序員能夠迅速了解代碼背后的信息。完全沒有注釋的大段代碼對于閱讀者形同天書；注釋是給自己看的，應做到即使間隔很長時間，也能清晰理解當時的思路，注釋也是給繼任者看的，使其能夠快速接替自己的工作。
好的命名、代碼結(jié)構(gòu)是自解釋的，注釋力求精簡準確、表達到位。避免出現(xiàn)注釋的一個極端：過多過濫的注釋，因為代碼的邏輯一旦修改，修改注釋是相當大的負擔。
特殊注釋標記，請標明標記人與標記時間。注意及時處理這些標記，通過標記掃描經(jīng)常處理此類標記。有時候線上故障就來源于這些標記處的代碼。
