Java程序中Doc文檔註釋示例教程

Posted on by

許多人寫代碼時總不喜歡寫註釋，每個程序員如此，嘿嘿，我也一樣

不過，話說回來，該寫還是要寫哦！沒人會喜歡一個不寫註釋的程序員，當然，也沒有一個喜歡寫註釋的程序員，今天，我們就來說說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文檔註釋的資料請關註WalkonNet其它相關文章！

推薦閱讀：