最近看源碼，一些Javadoc常見的注釋整理下
Javadoc是Sun公司提供的一個技術，從程序源代碼中抽取類、方法、成員等注釋形成一個和源代碼配套的API幫助文檔。
Javadoc命令是用來生成自己的API文檔，使用方式：
javadoc 源文件名.java
javadoc -d 文檔存放目錄 源文件名.java
通過IDEA生成Javadoc ： Tools -> Generate JavaDoc
javadoc標簽
| 標簽 | 說明 |
|---|---|
| @author | 作者標識 |
| @version | 版本號 |
| @return | 對函數(shù)返回值的描述 |
| @deprecated | 標識過期API（為了保證兼容性，仍可用，但不推薦用） |
| @throws | 構造函數(shù)或方法會拋出的異常 |
| @exception | 同@throws |
| @see | 引用，查看相關的內容，如類，方法，變量等，必須頂頭寫 |
| {@link 包.類#成員} | 引用，同@see，但可寫在任意位置 |
| {@value} | 對常量注釋，如果其值包含在文檔中，通過改標簽引用常量的值 |
| {@code}} | {@code text}將文本標記為code，會被解析成 text } ,在Javadoc成只要涉及到類名或者方法名，都需要使用@code進行標記 |
| @param | 說明方法的參數(shù) |
| @inheritDoc | 用于繼承父類中的Javadoc，父類的文檔注釋，被繼承到了子類 |
javadoc注釋規(guī)范
一、 Java文檔
|
1
2
3
|
// 注釋一行/ * */ 注釋若干行 /** ……*/ 注釋若干行，寫入Javadoc文檔 |
二、文檔格式
寫在類上的文檔標注一般分為三段：
第一段：概要描述，通常用一句話或者一段話簡要描述該類的作用，以英文句號結束
第二段：詳細描述，通常用一段或者多段話來詳細描述該類的作用，一般每段話都以英文句號作為結束
第三段：文檔標注，用于標注作者，創(chuàng)建時間，參閱類等信息
|
1
2
3
|
生成文檔是HTML格式。換行<br>分段<p>(寫在段前）) |
示例
|
1
2
3
4
5
6
7
8
9
10
|
/** * show 方法的簡述.* <p>show 方法的詳細說明第一行<br> * show 方法的詳細說明第二行 * @param b true 表示顯示，false 表示隱藏 * @return 沒有返回值 */public void show(boolean b) { frame.show(b); } |
補充：Java的三種注釋 Javadoc標記*
三種注釋方法：
1、單行注釋 //注釋的內容
2、多行注釋 /*......*/
3、/**......*/，這種方式和第二種方式相似。這種格式是為了便于javadoc程序自動生成文檔。
下面介紹一下Javadoc的標記：
|
JavaDoc 標 記 |
解釋 |
|
@version |
指定版本信息 |
|
@since |
指定最早出現(xiàn)在哪個版本 |
|
@author |
指定作者 |
|
@see |
生成參考其他的JavaDoc文檔的連接 |
|
@link |
生成參考其他的JavaDoc文檔，它和@see標記的區(qū)別在于，@link標記能夠嵌入到注釋語句中，為注釋語句中的特殊詞匯生成連接。 eg.{@link Hello} |
|
@deprecated |
用來注明被注釋的類、變量或方法已經不提倡使用，在將來的版本中有可能被廢棄 |
|
@param |
描述方法的參數(shù) |
|
@return |
描述方法的返回值 |
|
@throws |
描述方法拋出的異常，指明拋出異常的條件 |
特別聲明：
（1）javadoc針對public類生成注釋文檔
（2）javadoc只能在public、protected修飾的方法或者屬性之上
（3）javadoc注釋的格式化：前導*號和HTML標簽
（4）javadoc注釋要僅靠在類、屬性、方法之前
下面主要舉例說明第三種注釋的應用：
（1）首先編寫.java文件
（2）在命令行中執(zhí)行以下dos命令：
javadoc *.java //根據(jù)相應的Java源代碼及其說明語句生成HTML文檔
//javadoc標記：是@開頭的，對javadoc而言，特殊的標記。
（3）在當前目錄下就會產生doc文件夾，里面有一系列的.html文件
附上代碼：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
<span style="font-size:18px;">*//**javadoc注釋的內容*/public class Hello{ /**屬性上的注釋*/ public String name; /**這是main方法,是程序的入口 *@param args 用戶輸入參數(shù) */ public static void main(String[] args){ System.out.println("Hello World!"); f1(); } /** 這是第1個方法,其作用是...*/ public static void f1(){ System.out.println("f1()！"); }}</span> |
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
|
<span style="font-size:18px;">import java.io.IOException;/**javadoc注釋內容*@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 輸入參數(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
|
1
|
javadoc -version -author -d doc *.java |
（其中用-version用于提取源文件中的版本信息 -author用于提取源文件中的作者信息）
以上為個人經驗，希望能給大家一個參考，也希望大家多多支持服務器之家。如有錯誤或未考慮完全的地方，望不吝賜教。
原文鏈接：https://blog.csdn.net/linton1/article/details/93733508
