在多人合作的項目中乓搬，詳細而有價值的代碼注釋顯得尤為重要。這不僅僅減少了組內(nèi)開發(fā)人員之間的無效溝通萨驶，也可以利用Javadoc工具歉摧，生成可對外發(fā)布的API文檔。也潛在的強制開發(fā)人員規(guī)劃好代碼結(jié)構(gòu)腔呜，比如類和方法的單一性問題等叁温。
Tips:本文只講述javadoc及Java注釋規(guī)范，關(guān)于kotlin注釋規(guī)范及 Dokka的使用核畴，請參考官方文檔：編寫Kotlin代碼文檔

本文主要內(nèi)容包含一下幾個方面：

• 術(shù)語介紹

• 注釋格式

• 塊標簽

• 內(nèi)聯(lián)標簽

• 注釋分類

• 源代碼與生成API文檔示例

• IDE注釋模板配置

• 參考資料

一膝但、術(shù)語介紹

1、文檔注釋

java源代碼中的特殊注釋以/** ... */定義符谤草。這些注釋用javadoc處理以生成API文檔跟束。

2莺奸、javadoc

把文檔注釋生成API文檔的JDK工具

3、源文件

Javadoc工具可以生成以下四種不同類型的“源”文件的輸出
1.Java類(.java)的源代碼文件——這些文件包含類冀宴、接口灭贷、字段、構(gòu)造函數(shù)和方法注釋
2.包注釋文件——這些文件包含包注釋
3.概述注釋文件——這些文件包含關(guān)于軟件包集的注釋
4.雜項未處理的文件——包括圖像略贮、示例源代碼甚疟、類文件、applet刨肃、HTML文件古拴，以及任何您可能希望從前面的文件中引用的文件箩帚。

4真友、塊標簽

@tag 格式的標簽（不被{ }包圍的標簽）為塊標簽，只能在主要描述（類注釋中對該類的詳細說明為主要描述）后面的標簽部分（如果塊標簽放在主要描述的前面紧帕，則生成 API 幫助文檔時會檢測不到主要描述）盔然。

5、內(nèi)聯(lián)標簽

{@tag} 格式的標簽（由{ }包圍的標簽）為內(nèi)聯(lián)標簽是嗜，可以放在主要描述中的任何位置或塊標簽的注釋中愈案。

二、文檔注釋格式

doc注釋是用HTML編寫的鹅搪，并且必須在類站绪，字段，構(gòu)造函數(shù)或方法聲明之前丽柿。它由兩部分組成-描述和標簽恢准。
類上的文檔標注順序：
1.概要描述，一句簡要描述該類的作用甫题，以句號作為結(jié)束馁筐。
2.詳細描述，用一段或者多段話來詳細描述該類的作用坠非，一般每段話都以句號作為結(jié)束敏沉。詳細描述中可以使用html標簽，如 <p>炎码、<pre>盟迟、<a>、<ul>潦闲、<i>等標簽攒菠， 通常詳細描述都以段落p標簽開始。詳細描述和概要描述中間通常有一個空行來分割矫钓。
3.文檔標注要尔，用于標注作者舍杜、創(chuàng)建時間、參閱類等信息
方法上文檔標注順序：
1.概要描述赵辕，一句簡要描述該方法的作用既绩，以句號作為結(jié)束
2.詳細描述，一段或者多段話來詳細描述該方法的作用还惠，一般每段話都以句號作為結(jié)束饲握。通常都以p標簽開始，而且p標簽通常都是單標簽蚕键，不使用結(jié)束標簽救欧，其中使用最多的就是<p>、<pre>锣光、<ul>笆怠、<i>。pre元素可定義預格式化的文本誊爹。被包圍在pre元素中的文本通常會保留空格和換行符蹬刷。而文本也會呈現(xiàn)為等寬字體，pre標簽的一個常見應用就是用來表示計算機的源代碼频丘。
一般p經(jīng)常結(jié)合pre使用办成，或者pre結(jié)合@code共同使用(推薦@code方式)
一般經(jīng)常使用pre來舉例如何使用方法
3.文檔標注，用于標注參數(shù)搂漠、返回值迂卢、異常、參閱等

示例：

   /**
     * 返回一個Image對象桐汤，然后可以將其繪制在屏幕上而克。
     * url參數(shù)必須指定一個絕對<a href="#{@link}"> {@link URL} </a>.
     * name參數(shù)是一個相對于url參數(shù)的說明符。
     * <p>
     * 無論圖片是否存在此方法都會立即返回
     *
     * @param url  圖片路徑
     * @param name 圖片名字
     * @return 返回一個 <a href="#{@link}"> {@link Image} </a>
     * @see Image
     */
    public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } catch (MalformedURLException e) {
            return null;
        }
    }

    /**
     * 通過Url獲取Image
     *
     * @param url 圖片地址
     * @return 返回一個 <a href="#{@link}"> {@link Image} </a>
     */
    private Image getImage(URL url) {
        return null;
    }

文檔注釋的第一句都為摘要句惊科，介紹類或者方法的作用拍摇。緊挨著寫的就是以@開頭的標簽

三、塊標簽

常用標簽以及同時出現(xiàn)在同一注釋塊中的順序如下：

• @author （僅類和接口是必需的）
• @version（僅類和接口是必需的）
• @param （僅方法和構(gòu)造函數(shù)）
• @return （僅方法）
• @throws
• @see
• @since
• @deprecated

@author

適用范圍：類馆截、接口級別充活。
意義作用：指定對包或者類做出巨大貢獻的技術(shù)人員，方便后續(xù)組內(nèi)溝通蜡娶。
使用規(guī)則：可以標注0個或者多個混卵，@author標記并不重要，因為在生成API規(guī)范時不包含@author標記窖张，因此只有查看源代碼的人才能看到它幕随。如果作者不明，請使用“ unscribed”作為@author的參數(shù)宿接。

/**
 *  @author smile1
 *  @author smile2
 */

@version

適用范圍：類赘淮、接口級別辕录。
意義作用：指定版本文本，用于標記保存當前代碼所屬的版本號梢卸。
使用規(guī)則：可以標注0個或者多個

/**
 * @version 1.15, 13 Dec 2006
 */

@param

適用范圍：主要用于標記方法或者構(gòu)造函數(shù)中參數(shù)走诞。
意義作用：解釋參數(shù)代表意義
使用規(guī)則：可以標注0個或者多個，@param標記后跟參數(shù)的名稱（不是數(shù)據(jù)類型）蛤高，后跟參數(shù)的描述蚣旱，描述中的第一個名詞是參數(shù)的數(shù)據(jù)類型。

   /**
     * 通過Url獲取Image
     *
     * @param url 圖片地址
     * @return 返回一個 <a href="#{@link}"> {@link Image} </a>
     */
    private Image getImage(URL url) {
        return null;
    }

@return

適用范圍：僅可以指定方法的返回值戴陡，
意義作用：主要描述文本應描述返回類型和允許的值范圍塞绿，對于返回void的方法和構(gòu)造函數(shù)，請忽略@return恤批；

    /**
     * @return <code> true </ code>圖像已完全加載并成功繪制
     *         <code> false </ code> 否則
     */
    public abstract boolean drawImage();

@throws（@exception是原始標記）

適用范圍：僅可以指定方法
意義作用：對于任何已檢查異常以及調(diào)用者想要捕獲的未檢查異常都應該包含該標記异吻。不可預測的錯誤異常不必標記，例如NPE开皿。
使用規(guī)則：可以標注0個或者多個涧黄，@throws標記后跟異常類型篮昧，后跟異常描述赋荆。
檢查異常：除了類RuntimeException、Error及其子類懊昨，所有其他異常子類都是檢查異常窄潭。
未檢查異常：類RuntimeException、Error及其子類酵颁。

   /**
     *  用于案列展示
     * @throws IOException 如果出現(xiàn)輸入或輸出異常
     */
    public void foo() throws IOException {

    }

@see

適用范圍：任何注釋文檔
意義作用：添加帶有鏈接或文本條目嫉你。
使用規(guī)則：可以標注0個或者多個，@see "字符串" 則顯示字符串 躏惋，@see <a href="URL＃值">標簽</a> 給顯示字符串添加鏈接幽污。

• 多個@see顯示順序總體由小見大，如下所示：*
  @see #field
  @see #Constructor(Type, Type...)
  @see #Constructor(Type id, Type id...)
  @see #method(Type, Type,...)
  @see #method(Type id, Type, id...)
  @see Class
  @see Class#field
  @see Class#Constructor(Type, Type...)
  @see Class#Constructor(Type id, Type id)
  @see Class#method(Type, Type,...)
  @see Class#method(Type id, Type id,...)
  @see package.Class
  @see package.Class#field
  @see package.Class#Constructor(Type, Type...)
  @see package.Class#Constructor(Type id, Type id)
  @see package.Class#method(Type, Type,...)
  @see package.Class#method(Type id, Type, id)
  @see package

    /*
     * @see       #finalize()
     * @see       Component#getGraphics()
     * @see       Component#paint(Graphics)
     * @see       Component#update(Graphics)
     */
    public abstract void dispose();

@since

適用范圍：任何注釋文檔
意義作用：表示此更改或功能自since-text指定的軟件版本以來就已經(jīng)存在
使用規(guī)則：可以標注0個或者多個簿姨，@since 1.5 意味著“自從從1.5版本以后就有該方法”距误。

/*
* @since     1.0
*/
public abstract void dispose();

@deprecated

適用范圍：任何注釋文檔
意義作用: 表示不推薦使用
使用規(guī)則：使用@Deprecated注解棄用程序元素，然后編寫@deprecated扁位，進行解釋說明准潭。

/ **
 * @deprecated 從JDK 1.1開始，由{@link #setBounds（int域仇，int刑然，int，int）}取代
 * /
   @Deprecated
    public void setBounds(int a,int b){
        
    }

@serial

作用：說明一個序列化屬性
使用規(guī)則：@serial 字段描述 | include | exclude
示例：@serial 描述

@serialField

作用：記錄可序列化類serialPersistentFields成員的ObjectStreamField組件
使用規(guī)則：@serialField field-name field-type field-description

@serialData

作用：數(shù)據(jù)描述以序列化的形式記錄數(shù)據(jù)的類型和順序
使用規(guī)則：@serialData data-description
使用范圍：可以在writeObject暇务、readObject泼掠、writeExternal怔软、readExternal、writeReplace和readResolve方法的文檔注釋中使用择镇。

四爽雄、內(nèi)聯(lián)標簽（使用范圍：注釋內(nèi)容內(nèi)部嵌套）

{@code text}

作用：以代碼字體顯示文本，而不將文本解釋為HTML標記或嵌套的javadoc標記沐鼠。
如下：
{@code A<B>C}
網(wǎng)頁顯示為：
A<B>C（代碼字體）

{@literal text}

作用：顯示文本挚瘟，而不將文本解釋為HTML標記或嵌套的javadoc標記。
如下：
{@literal A<B>C}
網(wǎng)頁顯示為：
A<B>C
<B>不會顯示為粗體饲梭，也不是代碼字體

{@docRoot}

作用：指明當前文檔根目錄的路徑

{@inheritDoc}

作用：從直接父類繼承的注釋
使用規(guī)則：

• 在方法的主描述塊中乘盖。在這種情況下，主描述是從層次結(jié)構(gòu)上的類或接口復制的憔涉。
• 在方法的@return订框、@param和@throws標記的文本參數(shù)中。在本例中兜叨，標記文本從層次結(jié)構(gòu)中相應的標記復制穿扳。

{@link}

作用：插入一個到另一個主題的鏈接
使用規(guī)則:{@link package.class#成員 標簽},

    /**
     * 使用{@link #getComponentAt（int，int）getComponentAt}方法国旷。
     */
    public  void getComponent(){
        
    }

在網(wǎng)頁上顯示：
使用getComponentAt方法矛物。

{@linkplain}

作用：插入一個到另一個主題的鏈接，但是該鏈接顯示純文本字體
使用規(guī)則：{@linkplain package.class#成員 標簽}跪但，與相同{@link}履羞，不同之處在于鏈接的標簽以純文本而非代碼字體顯示。

    /**
     *請參閱{@linkplain add() 加法函數(shù)}
     */

在網(wǎng)頁上顯示為：
請參閱加法函數(shù)屡久。

{@value}

作用：顯示常量的值忆首，該常量必須是 static 屬性。
使用規(guī)則：
1.當{@value}在靜態(tài)字段的doc注釋中使用（不帶任何參數(shù)）時被环，它將顯示該常量的值糙及。
2.與任何文檔注釋中的package.class＃field參數(shù)一起使用時，它將顯示指定常量的值筛欢。

  /**
     * 這個常數(shù)的值是{@value}.
     */
    public static final String SCRIPT_START = "script"
  / ** 
     *以{@value #SCRIPT_START}開頭的腳本進行評估浸锨。
     * / 
    public String evalScript（String script）{ 

    }

五、注釋分類

1.類源代碼文件

每個類或接口及其成員可以在.java文件中包含自己的文檔注釋悴能。有關(guān)這些文檔注釋的更多詳細信息揣钦。主要分為：類注釋，方法注釋漠酿，字段（域）注釋冯凹。

如下：
類注釋

/**
 * 表示屏幕上窗口的類。
 * 例如:
 * <pre>
 *    Window win = new Window(parent);
 *    win.show();
 * </pre>
 *
 * @author  smile
 * @version 1.15，2006年12月13日
 * @see     java.awt.BaseWindow
 * @see     java.awt.Button
 */
class Window extends BaseWindow {
   ...
}

方法注釋

 /**
     * 返回指定索引處的字符宇姚。 
     * 索引的范圍是<code>0</code> 到 <code>length() - 1</code>.
     *
     * @param     所需字符的索引匈庭。
     * @return    所需的字符。
     * @exception StringIndexOutOfRangeException
     *              如果索引不在范圍內(nèi) <code>0</code>
     *              到 <code>length()-1</code>.
     * @see       java.lang.Character#charValue()
     */
    public char charAt(int index) {
       ...
    }

字段注釋

/**
     * 分量的x坐標浑劳。
     *
     * @see #getLocation()
     */
    int x = 1263732;

2.包注釋文件

每個包都可以有自己的文檔注釋,包含在它自己的“源”文件中,Javadoc工具將合并到它生成的包摘要頁面中阱持。要創(chuàng)建程序包注釋文件，可以選擇兩個文件之一來放置注釋魔熏。package-infojava或者package.html衷咽。

package-info.java例子如下：
在com.example.utils包下創(chuàng)建package-info.java

/**
 * 提供項目所需的各種工具類
 * <p>
 *包下類簡介
 *
 * @author aurhor1;
 * @author aurhor2
 * @since 1.0
 */
package com.example.utils;

3.概述注釋文件

每個應用程序或包集都可以有自己的概述文檔注釋，保存在它自己的“源”文件中蒜绽，Javadoc工具將把它合并到它生成的概述頁面中镶骗。

4.雜項未處理的文件

在源文件中包含希望Javadoc工具復制到目標目錄的任何雜項文件。這些文件通常包括圖形文件躲雅、示例Java源文件(. Java)和類文件(.class)鼎姊，以及獨立的HTML文件，這些文件的內(nèi)容會壓倒普通Java源文件的文檔注釋相赁。

六相寇、示例

該示例代碼以及API文檔：github地址

package com.example.shareelem.exception;

import com.example.shareelem.NamingException;

/**
 * 此異常用于描述解析鏈接時遇到的問題。
 * 將附加信息添加到基本NamingException中以進行精確定位
 * 鏈接問題钮科。
 * <p>
 * 類似于NamingException如何捕獲名稱解析信息唤衫，
 * LinkException捕獲精確定位的“鏈接”名稱解析信息
 * 解決鏈接時遇到的問題。所有這些領(lǐng)域可能
 * 為空跺嗽。
 * <ul>
 * <li> 鏈接解析名稱战授。鏈接名稱已解決的部分。
 * <li> 鏈接解析的對象桨嫁。鏈接名稱解析的對象。
 * <li> 鏈接剩余名稱份帐。鏈接名稱尚未解析的部分璃吧。
 * <li> 鏈接說明。詳細說明鏈接解析失敗的原因废境。
 * </ul>
 *
 * <p>
 * LinkException實例未針對并發(fā)進行同步
 * 多線程訪問畜挨。多個線程試圖訪問和修改一個LinkException實例應鎖定該對象。
 *
 * @author author1
 * @author author2
 * @see Context#lookupLink
 * @see LinkRef
 * @since 1.3
 */


/*<p>
 * LinkException對象的序列化形式包括
 *其NamingException超類的序列化字段噩凹，鏈接已解析
 *名稱（一個名稱對象）巴元，鏈接解析對象，鏈接剩余名稱
 *（一個Name對象）驮宴，以及鏈接說明String逮刨。
 */


public class LinkException extends NamingException {
    /**
     * 包含鏈接中已成功解析的部分。
     * 這是一個復合名稱堵泽，可以為null修己。
     * 此字段由構(gòu)造函數(shù)初始化恢总。
     * 您應該訪問和操作此字段
     * 通過其get和set方法。
     *
     * @serial
     * @see #getLinkResolvedName
     * @see #setLinkResolvedName
     */
    protected Name linkResolvedName;

    /**
     * 包含鏈接部分解析成功的對象睬愤。
     * 可以為null片仿。該字段由構(gòu)造函數(shù)初始化。
     * 您應該訪問和操作此字段
     * 通過其get和set方法尤辱。
     *
     * @serial
     * @see #getLinkResolvedObj
     * @see #setLinkResolvedObj
     */
    protected Object linkResolvedObj;

    /**
     * 包含尚未解析的其余鏈接名稱砂豌。
     * 這是一個復合名稱，可以為null光督。
     * 此字段由構(gòu)造函數(shù)初始化奸鸯。
     * 您應該訪問和操作此字段
     * 通過其get和set方法。
     *
     * @serial
     * @see #getLinkRemainingName
     * @see #setLinkRemainingName
     */
    protected Name linkRemainingName;

    /**
     * 包含為什么鏈接解析失敗的例外可帽。
     * 可以為null娄涩。該字段由構(gòu)造函數(shù)初始化。
     * 您應該訪問和操作此字段
     * 通過其get和set方法映跟。
     *
     * @serial
     * @see #getLinkExplanation
     * @see #setLinkExplanation
     */
    protected String linkExplanation;

    /**
     * 構(gòu)造一個帶有解釋的LinkException的新實例
     * 所有其他字段均初始化為null蓄拣。
     *
     * @param explanation 說明可能為空的字符串，其中包含其他
     *                    有關(guān)此異常的詳細信息努隙。
     * @see java.lang.Throwable#getMessage
     */
    public LinkException(String explanation) {
        super(explanation);
        linkResolvedName = null;
        linkResolvedObj = null;
        linkRemainingName = null;
        linkExplanation = null;
    }

    /**
     * 構(gòu)造一個LinkException的新實例球恤。
     * 所有與鏈接無關(guān)和與鏈接有關(guān)的字段均初始化為null。
     */
    public LinkException() {
        super();
        linkResolvedName = null;
        linkResolvedObj = null;
        linkRemainingName = null;
        linkExplanation = null;
    }

    /**
     * 檢索已解析的鏈接名稱的開頭部分
     * 成功地荸镊。
     *
     * @return 鏈接名稱中已成功解析的部分咽斧。
     * 這是一個綜合名稱。它可以為null躬存，這意味著
     * 尚未設置鏈接解析名稱字段张惹。
     * @see #getLinkResolvedObj
     * @see #setLinkResolvedName
     */
    public Name getLinkResolvedName() {
        return this.linkResolvedName;
    }

    /**
     * 檢索鏈接名稱的剩余未解決部分。
     *
     * @return 鏈接名稱中尚未解析的部分岭洲。
     * 這是一個綜合名稱宛逗。它可以為null，這意味著
     * 鏈接剩余名稱字段尚未設置盾剩。
     * @see #setLinkRemainingName
     */
    public Name getLinkRemainingName() {
        return this.linkRemainingName;
    }

    /**
     * 檢索成功解析的對象雷激。
     * 這是解析的鏈接名稱所綁定的對象。
     *
     * @return 到目前為止已解決的可能為空的對象告私。
     * 如果為null屎暇，則表示尚未設置鏈接解析對象字段。
     * @see #getLinkResolvedName
     * @see #setLinkResolvedObj
     */
    public Object getLinkResolvedObj() {
        return this.linkResolvedObj;
    }

    /**
     * 檢索與遇到的問題相關(guān)的解釋
     * 解析鏈接時驻粟。
     *
     * @return 可能為空的詳細信息字符串根悼，解釋有關(guān)該問題的更多信息
     * 解決鏈接。
     * 如果為null，則表示沒有
     * 此異常的鏈接詳細信息番挺。
     * @see #setLinkExplanation
     */
    public String getLinkExplanation() {
        return this.linkExplanation;
    }

    /**
     * 設置與遇到的問題相關(guān)的解釋
     * 解析鏈接時唠帝。
     *
     * @param msg msg可能為null的詳細信息字符串，解釋有關(guān)該問題的更多信息
     *            解決鏈接玄柏。如果為null襟衰，則表示將不記錄任何細節(jié)。
     * @see #getLinkExplanation
     */
    public void setLinkExplanation(String msg) {
        this.linkExplanation = msg;
    }

    /**
     * 設置此異常的已解析鏈接名稱字段粪摘。
     * <p>
     * < tt > name </ tt>是一個復合名稱瀑晒。如果要設定
     * 此字段使用復合名稱或字符串，您必須
     * “ stringify”復合名稱徘意，并創(chuàng)建一個復合
     * 使用字符串用單個組件命名苔悦。那你可以
     * 使用生成的復合名稱調(diào)用此方法。
     * <p>
     * 復制并存儲< code > name </ code>椎咧。
     * 隨后對< code > name </ code>的更改不會
     * 在此NamingException中影響副本玖详，反之亦然。
     *
     * @param name name設置解析鏈接名稱的名稱勤讽◇可以為空。
     *             如果為null脚牍，則將鏈接解析的名稱字段設置為null向臀。
     * @see #getLinkResolvedName
     */
    public void setLinkResolvedName(Name name) {
        if (name != null) {
            this.linkResolvedName = (Name) (name.clone());
        } else {
            this.linkResolvedName = null;
        }
    }

    /**
     * 設置此異常的其余鏈接名稱字段。
     * <p>
     * < tt > name </ tt>是一個復合名稱诸狭。如果要設定
     * 此字段使用復合名稱或字符串券膀，您必須
     * “ stringify”復合名稱，并創(chuàng)建一個復合
     * 使用字符串用單個組件命名驯遇。那你可以
     * 使用生成的復合名稱調(diào)用此方法芹彬。
     * <p>
     * 復制并存儲< code > name </ code>。
     * 隨后對< code > name </ code>的更改不會
     * 在此NamingException中影響副本妹懒，反之亦然雀监。
     *
     * @param name 設置剩余鏈接名稱的名稱≌；＃可以為空。
     *             如果為null好乐，則將剩余的name字段設置為null匾竿。
     * @see #getLinkRemainingName
     */
    public void setLinkRemainingName(Name name) {
        if (name != null)
            this.linkRemainingName = (Name) (name.clone());
        else
            this.linkRemainingName = null;
    }

    /**
     * 設置此異常的鏈接解析對象字段。
     * 這表示鏈接名稱的最后一個成功解析的對象蔚万。
     *
     * @param obj 設置鏈接解析對象的對象￡腔牛可以為空。
     *            如果為null斋攀，則將鏈接解析對象字段設置為null已卷。
     * @see #getLinkResolvedObj
     */
    public void setLinkResolvedObj(Object obj) {
        this.linkResolvedObj = obj;
    }

    /**
     * 生成此異常的字符串表示形式淳蔼。
     * 此字符串包含NamingException信息以及
     * 鏈接的剩余名稱。
     * 此字符串用于調(diào)試鹉梨，不用于解釋
     * 以編程方式讳癌。
     *
     * @return 此鏈接異常的非空字符串表示形式。
     */
    public String toString() {
        return super.toString() + "; Link Remaining Name: '" +
                this.linkRemainingName + "'";
    }

    /**
     * 生成此異常的字符串表示形式存皂。
     * 此字符串包含NamingException信息以及
     * 解決鏈接的其他信息。
     * 如果'detail'為true骤菠，則該字符串還包含有關(guān)以下內(nèi)容的信息
     * 鏈接解析的對象猜憎。如果為false，則此方法相同
     * 作為toString（）的形式截亦，不接受任何參數(shù)柬讨。
     * 此字符串用于調(diào)試，不用于解釋
     * 以編程方式却桶。
     *
     * @param detail 如果為true蔗牡，請?zhí)砑佑嘘P(guān)已解析鏈接的信息
     *               目的。
     * @return此鏈接異常的非空字符串表示形式嘁扼。
     */
    public String toString(boolean detail) {
        if (!detail || this.linkResolvedObj == null)
            return this.toString();

        return this.toString() + "; Link Resolved Object: " +
                this.linkResolvedObj;
    }

    /**
     * 使用JNDI 1.1.1中的serialVersionUID進行互操作性
     */
    private static final long serialVersionUID = -7967662604076777712L;
};

七趁啸、生成API文檔

1.利用javadoc指令

javadoc -d api文檔目錄 -sourcepath java源碼目錄 -subpackages 包名
具體可參考：javadocoptions
如上例子生成API文檔則在dos中輸入：

javadoc -d D:\javadoc -encoding utf-8 -charset utf-8 F:\AndroidProject\ShareElem\app\src\main\java\com\example\share
elem\exception\LinkException.java

2.利用IDEA或者AndroidStudio IDE開發(fā)工具自帶的javadoc

打開AS工具Tools選項卡—GenerateJavaDoc

12.png

3.利用IDEJavadoc插件

setting—plugins下載javadoc插件

八不傅、IDE設置注釋模板

配置方法參考：IDEA注釋模板設置
類文件配置內(nèi)容

 /**
 * @author : user 
 * @createDate: datetime  
 * @updateUser: user 
 * @updateDate: datetime
 * @updateRemark: 
 */

八、參考資料

1.How to Write Doc Comments for the Javadoc Tool
2.The Java API Documentation Generator