Javadoc標簽和Javadoc注釋規(guī)范說明

更新時間：2021年02月08日 09:58:20 作者：恰克與飛鳥.

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

最近看源碼，一些Javadoc常見的注釋整理下

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

Javadoc命令是用來生成自己的API文檔，使用方式：

javadoc 源文件名.java

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

通過IDEA生成Javadoc ： Tools -> Generate JavaDoc

javadoc標簽

標簽	說明
@author	作者標識
@version	版本號
@return	對函數(shù)返回值的描述
@deprecated	標識過期API（為了保證兼容性，仍可用，但不推薦用）
@throws	構(gòu)造函數(shù)或方法會拋出的異常
@exception	同@throws
@see	引用，查看相關(guān)的內(nèi)容，如類，方法，變量等，必須頂頭寫
{@link 包.類#成員}	引用，同@see，但可寫在任意位置
{@value}	對常量注釋，如果其值包含在文檔中，通過改標簽引用常量的值
{@code}}	{@code text}將文本標記為code，會被解析成 text } ,在Javadoc成只要涉及到類名或者方法名，都需要使用@code進行標記
@param	說明方法的參數(shù)
@inheritDoc	用于繼承父類中的Javadoc，父類的文檔注釋，被繼承到了子類

javadoc注釋規(guī)范

一、 Java文檔

// 注釋一行
/ *  */ 注釋若干行 
/**  ……*/ 注釋若干行，寫入Javadoc文檔

二、文檔格式

寫在類上的文檔標注一般分為三段：

第一段：概要描述，通常用一句話或者一段話簡要描述該類的作用，以英文句號結(jié)束

第二段：詳細描述，通常用一段或者多段話來詳細描述該類的作用，一般每段話都以英文句號作為結(jié)束

第三段：文檔標注，用于標注作者，創(chuàng)建時間，參閱類等信息

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

示例

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

補充：Java的三種注釋 Javadoc標記*

三種注釋方法：

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

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

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

下面介紹一下Javadoc的標記：

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

特別聲明：

（1）javadoc針對public類生成注釋文檔

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

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

（4）javadoc注釋要僅靠在類、屬性、方法之前

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

（1）首先編寫.java文件

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

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

//javadoc標記：是@開頭的，對javadoc而言，特殊的標記。

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

附上代碼：

<span style="font-size:18px;">*/
/**javadoc注釋的內(nèi)容
*/
public class Hello{
  /**屬性上的注釋*/
  public String name;
  /**這是main方法,是程序的入口
  *@param args 用戶輸入?yún)?shù)
  */
  public static void main(String[] args){
 System.out.println("Hello World!");
    f1();
  }
  /** 這是第1個方法,其作用是...*/
  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>鏈接到另一個文檔{@link Hello},就這些
*see Hello
*/
public class HelloWorld{
 /**非public，protected 屬性上的注釋不生成*/
 public String name;
 /**這是main方法，是程序的入口
 *@param args 用戶輸入的參數(shù)，是數(shù)組
 *@throws IOException main方法io異常
 */
 public static void main(String args[]) throws IOException{
 System.out.println("hello World!");
 
 f1();
 f2(1);
 }
 /**這是第一個方法，其作用是....
 *@deprecated 從版本1.2開始，不再建議使用此方法
 */
 public static void f1(){
 System.out.println("fl()!");
 }
 /**這是第二個方法，其作用是....
 *@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標記，則在執(zhí)行javadoc命令時，要加-version -author