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