許多人寫代碼時(shí)總不喜歡寫注釋，每個(gè)程序員如此，嘿嘿，我也一樣
不過，話說回來，該寫還是要寫哦！沒人會喜歡一個(gè)不寫注釋的程序員，當(dāng)然，也沒有一個(gè)喜歡寫注釋的程序員，今天，我們就來說說Java注釋之一――Doc注釋
我們知道，Java支持 3 種注釋，分別是單行注釋、多行注釋和文檔注釋，我們來看看他們的樣子
//單行注釋
/*
多行注釋
*/
/**
*@...
*....
*文檔注釋
*/
可能許多萌新不明白，寫了這些注釋有什么用呢？
其實(shí)是因?yàn)槌鯇W(xué)者的代碼量少，沒有注釋也能快速查找、修改
當(dāng)代碼漸漸多了起來，注釋就是一個(gè)好東西了，不僅是為了自己可以清晰明了看清代碼，也是為了和你一起開發(fā)項(xiàng)目的成員一個(gè)方便
記住，改掉不寫注釋這種壞習(xí)慣！！！
那么，我們今天的主題來了，什么是Doc注釋呢？
javadoc是Sun公司提供的一個(gè)技術(shù)，它從程序源代碼中抽取類、方法、成員等注釋形成一個(gè)和源代碼配套的API幫助文檔。也就是說，只要在編寫程序時(shí)以一套特定的標(biāo)簽作注釋，在程序編寫完成后，通過Javadoc就可以同時(shí)形成程序的開發(fā)文檔了。
javadoc命令是用來生API文檔的，使用方式：使用命令行在目標(biāo)文件所在目錄輸入javadoc +文件名.java
這些復(fù)雜理論不必去糾結(jié)，要培養(yǎng)一種思想，去了解、去理解、去深入、去改變它，去懂得他，死死揪住理論是沒有效果的！
我們寫代碼，都是有規(guī)范的，如果你寫的代碼可以運(yùn)行，但是一團(tuán)亂麻，是沒人愿意使用的，因?yàn)殡y以維護(hù)，所以，代碼不只是單純的程序，在網(wǎng)絡(luò)世界，我更愿意稱之它為藝術(shù)品，需要你的精心鐫刻
可能有人會說，不就是注釋嗎？這有什么的
不過，這個(gè)Doc注釋可不與其他兩個(gè)注釋一樣，注釋也是存在規(guī)范的哦！
Doc注釋規(guī)范
格式：
寫在類上的文檔標(biāo)注一般分為三段：
第一段：概要描述，通常用一句或者一段話簡要描述該類的作用，以英文句號作為結(jié)束
第二段：詳細(xì)描述，通常用一段或者多段話來詳細(xì)描述該類的作用，一般每段話都以英文句號作為結(jié)束
第三段：文檔標(biāo)注，用于標(biāo)注作者、創(chuàng)建時(shí)間、參閱類等信息
這里我要擴(kuò)展一點(diǎn)知識，我們的Doc注釋可以使用Dos命令或者IDE工具生成一個(gè)Doc文檔，這個(gè)文檔是HTML語言來貫穿的，所以在注釋里面可以搭配一些簡單的HTML代碼，比如下面這幾個(gè)
換行<br>
分段<p>(寫在段前）
放個(gè)實(shí)例樣式圖：
@符號的用處
我們在寫Doc注釋時(shí)，/** 后直接回車，會自動生成后面的注釋框架，和部分@符號，那么這些@符號有什么用呢？
| 標(biāo)簽 | 描述 | 示例 |
|---|---|---|
| @author | 標(biāo)識一個(gè)類的作者，一般用于類注釋 | @author description |
| @deprecated | 指名一個(gè)過期的類或成員，表明該類或方法不建議使用 | @deprecated description |
| {@docRoot} | 指明當(dāng)前文檔根目錄的路徑 | Directory Path |
| @exception | 可能拋出異常的說明，一般用于方法注釋 | @exception exception-name explanation |
| {@inheritDoc} | 從直接父類繼承的注釋 | Inherits a comment from the immediate surperclass. |
| {@link} | 插入一個(gè)到另一個(gè)主題的鏈接 | {@link name text} |
| {@linkplain} | 插入一個(gè)到另一個(gè)主題的鏈接，但是該鏈接顯示純文本字體 | Inserts an in-line link to another topic. |
| @param | 說明一個(gè)方法的參數(shù)，一般用于方法注釋 | @param parameter-name explanation |
| @return | 說明返回值類型，一般用于方法注釋，不能出現(xiàn)再構(gòu)造方法中 | @return explanation |
| @see | 指定一個(gè)到另一個(gè)主題的鏈接 | @see anchor |
| @serial | 說明一個(gè)序列化屬性 | @serial description |
| @serialData | 說明通過 writeObject() 和 writeExternal() 方法寫的數(shù)據(jù) | @serialData description |
| @serialField | 說明一個(gè) ObjectStreamField 組件 | @serialField name type description |
| @since | 說明從哪個(gè)版本起開始有了這個(gè)函數(shù) | @since release |
| @throws | 和 @exception 標(biāo)簽一樣. | The @throws tag has the same meaning as the @exception tag. |
| {@value} | 顯示常量的值，該常量必須是 static 屬性。 | Displays the value of a constant, which must be a static field. |
| @version | 指定類的版本，一般用于類注釋 | @version info |
@后面我這里部分是英文，可以寫中文，比如 @author 小簡
如何生成Doc文檔
我們上面說過，寫了Doc注釋，可以生成一個(gè)Doc文檔，而且是HTML格式，那么我們怎么生成呢？
第一個(gè)：Dos命令生成
javadoc [options] [packagenames] [sourcefiles]
對格式的說明：
options 表示 Javadoc 命令的選項(xiàng)；
packagenames 表示包名；
sourcefiles 表示源文件名;
在 cmd（命令提示符）中輸入javadoc -help就可以看到 Javadoc 的用法和選項(xiàng)（前提是安裝配置了JDK），下面列舉 Javadoc 命令的常用選項(xiàng)：
| 名稱 | 說明 |
|---|---|
| -public | 僅顯示 public 類和成員 |
| -protected | 顯示 protected/public 類和成員（默認(rèn)值） |
| -package | 顯示 package/protected/public 類和成員 |
| -private | 顯示所有類和成員 |
| -d <directory> | 輸出文件的目標(biāo)目錄 |
| -version | 包含 @version 段 |
| -author | 包含 @author 段 |
| -splitindex | 將索引分為每個(gè)字母對應(yīng)一個(gè)文件 |
| -windowtitle <text> | 文檔的瀏覽器窗口標(biāo)題 |
用Doc生成又麻煩又慢，那還有沒有其他方法呢？
第二個(gè)：IDE工具生成
我們可以用Eclipse或者IDEA生成，Eclipse我不怎么用，用IDEA給你們演示一下吧！
在工具這個(gè)里面的JavaDoc里面，進(jìn)去后是這樣的
輸出目錄必須選擇，不然生成不了
注意了，因?yàn)镴ava的編碼與IDEA的編碼不一樣，所以在其他命令形參欄目里面，要填寫以下內(nèi)容
-encoding utf8 -docencoding utf8 -charset utf8
生成之后，是這樣的
好了，Doc注釋知道用就可以
最重要的是：一定要寫注釋，各位程序員們，未來可期，頂峰相見
以上就是Java程序中Doc文檔注釋示例教程的詳細(xì)內(nèi)容，更多關(guān)于Java程序Doc文檔注釋的資料請關(guān)注服務(wù)器之家其它相關(guān)文章！
原文鏈接：https://blog.csdn.net/qq_60750453/article/details/121024414
