Java程序中Doc文檔注釋示例教程
許多人寫代碼時(shí)總不喜歡寫注釋，每個(gè)程序員如此，嘿嘿，我也一樣
不過，話說回來，該寫還是要寫哦！沒人會(huì)喜歡一個(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ù)品，需要你的精心鐫刻
可能有人會(huì)說，不就是注釋嗎？這有什么的
不過，這個(gè)Doc注釋可不與其他兩個(gè)注釋一樣，注釋也是存在規(guī)范的哦！
Doc注釋規(guī)范
格式：
寫在類上的文檔標(biāo)注一般分為三段：
第一段：概要描述，通常用一句或者一段話簡(jiǎn)要描述該類的作用，以英文句號(hào)作為結(jié)束
第二段：詳細(xì)描述，通常用一段或者多段話來詳細(xì)描述該類的作用，一般每段話都以英文句號(hào)作為結(jié)束
第三段：文檔標(biāo)注，用于標(biāo)注作者、創(chuàng)建時(shí)間、參閱類等信息
這里我要擴(kuò)展一點(diǎn)知識(shí)，我們的Doc注釋可以使用Dos命令或者IDE工具生成一個(gè)Doc文檔，這個(gè)文檔是HTML語言來貫穿的，所以在注釋里面可以搭配一些簡(jiǎn)單的HTML代碼，比如下面這幾個(gè)
換行<br>
分段<p>(寫在段前）
放個(gè)實(shí)例樣式圖：
@符號(hào)的用處
我們?cè)趯慏oc注釋時(shí)，/** 后直接回車，會(huì)自動(dòng)生成后面的注釋框架，和部分@符號(hào)，那么這些@符號(hào)有什么用呢？
| 標(biāo)簽 | 描述 | 示例 |
|---|---|---|
| @author | 標(biāo)識(shí)一個(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 小簡(jiǎn)
如何生成Doc文檔
我們上面說過，寫了Doc注釋，可以生成一個(gè)Doc文檔，而且是HTML格式，那么我們?cè)趺瓷赡兀?/p>
第一個(gè)：Dos命令生成
javadoc [options] [packagenames] [sourcefiles]
對(duì)格式的說明：
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è)字母對(duì)應(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文檔注釋的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！
相關(guān)文章
Java并發(fā)編程之閉鎖與柵欄的實(shí)現(xiàn)
這篇文章主要介紹了Java并發(fā)編程之閉鎖與柵欄的實(shí)現(xiàn)，文中通過示例代碼介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2020-04-04
Maven根據(jù)不同環(huán)境打包不同配置文件的方法
這篇文章主要介紹了Maven根據(jù)不同環(huán)境打包不同配置文件的方法，小編覺得挺不錯(cuò)的，現(xiàn)在分享給大家，也給大家做個(gè)參考。一起跟隨小編過來看看吧2018-08-08
基于令牌桶的限流器注解的簡(jiǎn)單實(shí)現(xiàn)詳解
令牌桶算法是一種常用的流量控制算法，用于限制請(qǐng)求或事件的發(fā)生速率,這篇文章主要介紹了如何基于令牌桶實(shí)現(xiàn)限流器注解，需要的可以參考一下2023-08-08
Java中調(diào)用SQL Server存儲(chǔ)過程詳解
這篇文章主要介紹了Java中調(diào)用SQL Server存儲(chǔ)過程詳解,本文講解了使用不帶參數(shù)的存儲(chǔ)過程、使用帶有輸入?yún)?shù)的存儲(chǔ)過程、使用帶有輸出參數(shù)的存儲(chǔ)過程、使用帶有返回狀態(tài)的存儲(chǔ)過程、使用帶有更新計(jì)數(shù)的存儲(chǔ)過程等操作實(shí)例,需要的朋友可以參考下2015-01-01
這篇文章主要為大家介紹了java算法中暴力匹配算法及KMP算法解決字符串匹配的問題示例詳解，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進(jìn)步2021-11-11
Spring核心IoC容器的依賴注入接口和層級(jí)包命名規(guī)范
這篇文章主要介紹了Spring核心IoC容器的依賴注入接口和層級(jí)包命名規(guī)范,IOC又名控制反轉(zhuǎn),把對(duì)象創(chuàng)建和對(duì)象之間的調(diào)用過程,交給Spring進(jìn)行管理,目的是為了降低耦合度,需要的朋友可以參考下2023-05-05
從內(nèi)存地址解析Java的static關(guān)鍵字的作用
這篇文章主要介紹了從內(nèi)存地址解析Java的static關(guān)鍵字的作用,包括靜態(tài)成員變量和靜態(tài)方法等重要內(nèi)容,需要的朋友可以參考下2015-10-10
Spring框架開發(fā)IOC兩種創(chuàng)建工廠方法詳解
這篇文章主要介紹了Spring框架IOC兩種創(chuàng)建工廠方法詳解，文中附含詳細(xì)的代碼示例分別對(duì)靜態(tài)方法和實(shí)例方法創(chuàng)建工廠作了簡(jiǎn)要的分析2021-09-09
這篇文章主要為大家介紹了Guava反射工具使用示例詳解,有需要的朋友可以借鑒參考下,希望能夠有所幫助,祝大家多多進(jìn)步,早日升職加薪2023-12-12
這篇文章主要為大家詳細(xì)介紹了區(qū)塊鏈java代碼實(shí)現(xiàn)，具有一定的參考價(jià)值，感興趣的小伙伴們可以參考一下2018-01-01