Javadoc標(biāo)簽和Javadoc注釋規(guī)范說(shuō)明

更新時(shí)間：2021年02月08日 09:58:20 作者：恰克與飛鳥(niǎo).

這篇文章主要介紹了Javadoc標(biāo)簽和Javadoc注釋規(guī)范說(shuō)明，具有很好的參考價(jià)值，希望對(duì)大家有所幫助。一起跟隨小編過(guò)來(lái)看看吧

最近看源碼，一些Javadoc常見(jiàn)的注釋整理下

Javadoc是Sun公司提供的一個(gè)技術(shù)，從程序源代碼中抽取類(lèi)、方法、成員等注釋形成一個(gè)和源代碼配套的API幫助文檔。

Javadoc命令是用來(lái)生成自己的API文檔，使用方式：

javadoc 源文件名.java

javadoc -d 文檔存放目錄源文件名.java

通過(guò)IDEA生成Javadoc ： Tools -> Generate JavaDoc

javadoc標(biāo)簽

標(biāo)簽	說(shuō)明
@author	作者標(biāo)識(shí)
@version	版本號(hào)
@return	對(duì)函數(shù)返回值的描述
@deprecated	標(biāo)識(shí)過(guò)期A(yíng)PI（為了保證兼容性，仍可用，但不推薦用）
@throws	構(gòu)造函數(shù)或方法會(huì)拋出的異常
@exception	同@throws
@see	引用，查看相關(guān)的內(nèi)容，如類(lèi)，方法，變量等，必須頂頭寫(xiě)
{@link 包.類(lèi)#成員}	引用，同@see，但可寫(xiě)在任意位置
{@value}	對(duì)常量注釋?zhuān)绻渲蛋谖臋n中，通過(guò)改標(biāo)簽引用常量的值
{@code}}	{@code text}將文本標(biāo)記為code，會(huì)被解析成 text } ,在Javadoc成只要涉及到類(lèi)名或者方法名，都需要使用@code進(jìn)行標(biāo)記
@param	說(shuō)明方法的參數(shù)
@inheritDoc	用于繼承父類(lèi)中的Javadoc，父類(lèi)的文檔注釋?zhuān)焕^承到了子類(lèi)

javadoc注釋規(guī)范

一、 Java文檔

// 注釋一行
/ *  */ 注釋若干行 
/**  ……*/ 注釋若干行，寫(xiě)入Javadoc文檔

二、文檔格式

寫(xiě)在類(lèi)上的文檔標(biāo)注一般分為三段：

第一段：概要描述，通常用一句話(huà)或者一段話(huà)簡(jiǎn)要描述該類(lèi)的作用，以英文句號(hào)結(jié)束

第二段：詳細(xì)描述，通常用一段或者多段話(huà)來(lái)詳細(xì)描述該類(lèi)的作用，一般每段話(huà)都以英文句號(hào)作為結(jié)束

第三段：文檔標(biāo)注，用于標(biāo)注作者，創(chuàng)建時(shí)間，參閱類(lèi)等信息

生成文檔是HTML格式。
換行<br>
分段<p>(寫(xiě)在段前）)

示例

/** 
* show 方法的簡(jiǎn)述.
* <p>show 方法的詳細(xì)說(shuō)明第一行<br> 
* show 方法的詳細(xì)說(shuō)明第二行 
* @param b true 表示顯示，false 表示隱藏 
* @return 沒(méi)有返回值 
*/ 
public void show(boolean b) {
  frame.show(b);
  }

補(bǔ)充：Java的三種注釋 Javadoc標(biāo)記*

三種注釋方法：

1、單行注釋 //注釋的內(nèi)容

2、多行注釋 /*......*/

3、/**......*/，這種方式和第二種方式相似。這種格式是為了便于javadoc程序自動(dòng)生成文檔。

下面介紹一下Javadoc的標(biāo)記：

JavaDoc 標(biāo) 記	解釋
@version	指定版本信息
@since	指定最早出現(xiàn)在哪個(gè)版本
@author	指定作者
@see	生成參考其他的JavaDoc文檔的連接
@link	生成參考其他的JavaDoc文檔，它和@see標(biāo)記的區(qū)別在于，@link標(biāo)記能夠嵌入到注釋語(yǔ)句中，為注釋語(yǔ)句中的特殊詞匯生成連接。 eg.{@link Hello}
@deprecated	用來(lái)注明被注釋的類(lèi)、變量或方法已經(jīng)不提倡使用，在將來(lái)的版本中有可能被廢棄
@param	描述方法的參數(shù)
@return	描述方法的返回值
@throws	描述方法拋出的異常，指明拋出異常的條件

特別聲明：

（1）javadoc針對(duì)public類(lèi)生成注釋文檔

（2）javadoc只能在public、protected修飾的方法或者屬性之上

（3）javadoc注釋的格式化：前導(dǎo)*號(hào)和HTML標(biāo)簽

（4）javadoc注釋要僅靠在類(lèi)、屬性、方法之前

下面主要舉例說(shuō)明第三種注釋的應(yīng)用：

（1）首先編寫(xiě).java文件

（2）在命令行中執(zhí)行以下dos命令：

javadoc *.java //根據(jù)相應(yīng)的Java源代碼及其說(shuō)明語(yǔ)句生成HTML文檔

//javadoc標(biāo)記：是@開(kāi)頭的，對(duì)javadoc而言，特殊的標(biāo)記。

（3）在當(dāng)前目錄下就會(huì)產(chǎn)生doc文件夾，里面有一系列的.html文件

附上代碼：

<span style="font-size:18px;">*/
/**javadoc注釋的內(nèi)容
*/
public class Hello{
  /**屬性上的注釋*/
  public String name;
  /**這是main方法,是程序的入口
  *@param args 用戶(hù)輸入?yún)?shù)
  */
  public static void main(String[] args){
 System.out.println("Hello World!");
    f1();
  }
  /** 這是第1個(gè)方法,其作用是...*/
  public static void f1(){
   System.out.println("f1()！");
  }
}</span>

<span style="font-size:18px;">import java.io.IOException;
/**javadoc注釋內(nèi)容
*@since 1.0
*@version 1.1
*@author Blue Jey
*<br>鏈接到另一個(gè)文檔{@link Hello},就這些
*see Hello
*/
public class HelloWorld{
 /**非public，protected 屬性上的注釋不生成*/
 public String name;
 /**這是main方法，是程序的入口
 *@param args 用戶(hù)輸入的參數(shù)，是數(shù)組
 *@throws IOException main方法io異常
 */
 public static void main(String args[]) throws IOException{
 System.out.println("hello World!");
 
 f1();
 f2(1);
 }
 /**這是第一個(gè)方法，其作用是....
 *@deprecated 從版本1.2開(kāi)始，不再建議使用此方法
 */
 public static void f1(){
 System.out.println("fl()!");
 }
 /**這是第二個(gè)方法，其作用是....
 *@return 返回是否OK
 *@param i 輸入?yún)?shù)i
 *@see Hello
 *@throws IOException io異常
 */
 public static String f2(int i)throws IOException{
 System.out.println("f1()!");
 return "OK";
 }
 } </span>

注意：

如果源文件中有用到@version,@author標(biāo)記，則在執(zhí)行javadoc命令時(shí)，要加-version -author