Tag的一些慣例
一些Tags的說明
- @author：作者的姓名
- @version：版本號
- @param：對于參數(shù)的描述
- @return：對于返回內(nèi)容的描述
- @exception (和@throws是同義詞)：異常類的名稱和描述
- @see：表示去查看參考資料
- @since：表示這個變更或特性從什么時候或版本號等（由該標(biāo)簽中聲明的內(nèi)容決定）開始存在的
- @serial：用于表示序列化的字段（include | exclude）
- @deprecated：表示被棄用
- @link：用法{@link package.class#member label}。插入一個帶標(biāo)簽的鏈接，可以指向特定包、類或指定類的成員名稱的文檔。
- @literal：用法{@literal text}。用來顯示那些不用被HTML標(biāo)記或嵌套javadoc標(biāo)簽解析的文本。
Tags的順序
按照下面的順序?qū)憈ags：
- @author (僅用于類和接口，必須的)
- @version (僅用于類和接口，必須的)
- @param (僅用于方法和構(gòu)造函數(shù))
- @return (僅用于方法)
- @exception (和@throws是同義詞)
- @see
- @since
- @serial (或者@serialField，@serialData)
- @deprecated
對多個相同tags的排序
按照下面的慣例來使用多個相同tags。如果需要，可以用空白行（單*）來隔離這些包含多個相同tags的組。
- 多個@author標(biāo)簽，應(yīng)該按照發(fā)生時間順序排列，最早的發(fā)在最上面。
- 多個@param標(biāo)簽，應(yīng)該按照參數(shù)的聲明順序排列。
- 多個@throws標(biāo)簽（或@exception），應(yīng)該按照異常名稱的字母順序排列。
必須的Tags
按照慣例，每一個參數(shù)都應(yīng)該有一個@param標(biāo)簽，即使描述很明顯。每一個返回不是void的方法都應(yīng)該有一個@return標(biāo)簽，即使這個標(biāo)簽和方法的描述內(nèi)容重復(fù)。
