如何使用Java文檔註解產生文件？

我們知道，Java支援3 個註釋，分別是單行註解、多行註解和文件註釋，我們來看看他們的樣子

//單行註解
 
/*
多行註解
*/
 
/**
*@...
*....
*文件註解
*/

可能許多萌新不明白，寫了這些註解有什麼用呢？

其實是因為初學者的程式碼量少，沒有註解也能快速找到、修改

當程式碼漸漸多了起來，註解就是一個好東西了，不僅是為了自己可以清晰明了看清程式碼，也是為了和你一起開發專案的成員一個方便

記住，改掉不寫註解這種壞習慣！ ！ ！

那麼，我們今天的主題來了，什麼​​是Doc註解呢？

javadoc是Sun公司提供的技術，它從程式原始碼中抽取類別、方法、成員等註解形成一個和原始碼配套的API幫助文件。也就是說，只要在編寫程式時以一套特定的標籤作註釋，在程式編寫完成後，透過Javadoc就可以同時形成程式的開發文件了。

javadoc指令是用來生API文件的，使用方式：使用命令列在目標文件所在目錄輸入javadoc 檔名.java

這些複雜理論不必去糾結，要培養一種思想，去了解、去理解、去深入、去改變它，去懂得他，死死揪住理論是沒有效果的！

我們寫程式碼，都是有規範的，如果你寫的程式碼可以運行，但是一團亂麻，是沒人願意使用的，因為難以維護，所以，程式碼不只是單純的程序，在網路世界，我更願意稱之它為藝術品，需要你的精心錒刻

可能有人會說，不就是註釋嗎？這有什麼的

不過，這個Doc註解可不與其他兩個註解一樣，註解也是存在規範的哦！

Doc註解規格

格式：

 寫在類別上的文件標註一般分為三段：

第一段：摘要描述，通常用一句或一段話簡單描述該類的作用，以英文句號作為結束

第二段：詳細描述，通常用一段或多段話來詳細描述該類的作用，一般每段話都以英文句號作為結束

第三段：文檔標註，用於標註作者、創建時間、參閱類別等資訊

這裡我要擴展一點知識，我們的Doc註釋可以使用Dos命令或是IDE工具產生一個Doc文檔，這個文檔是HTML語言來貫穿的，所以在註解裡面可以搭配一些簡單的HTML程式碼，例如下面這幾個

換行

#分段

(寫在段落前）

放個實例樣式圖：

 @符號的用途

我們在寫Doc註解時，/** 後直接回車，會自動產生後面的註解框架，和部分@符號，那麼這些@符號有什麼用呢？

##Directory Path@exception可能會拋出例外的說明，一般用於方法註解@exception exception-name explanation#{@inheritDoc}從直接父類別繼承的註解#Inherits a comment from the immediate surperclass.#{@ link}插入一個到另一個主題的連結{@link name text}##{@linkplain}@param@return#@see@serial@serialData@serialField@since##說明從哪個版本開始有了這個函數@since release@throws和@exception 標籤一樣.The @throws tag has the same meaning as the @exception tag.{@value}顯示常數的值，常數必須是static 屬性。

標籤	描述	範例
#@author	標識一個類的作者，一般用於類別註釋	@author description
#@deprecated	指涉一個過期的類別或成員，表明該類別或方法不建議使用	@deprecated description
{@docRoot}	#指明目前文件根目錄的路徑
插入一個到另一個主題的鏈接，但是該鏈接顯示純文字字體	Inserts an in-line link to another topic.
說明一個方法的參數，一般用於方法註解	@param parameter-name explanation
說明傳回值類型，一般用於方法註釋，不能出現再構造方法中	@return explanation
指定一個到另一個主題的連結	@see anchor
#說明一個序列化屬性	@serial description
說明透過writeObject() 和writeExternal() 方法寫的資料	@serialData description
說明一個ObjectStreamField 元件	@serialField name type description

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 表示原始檔名; 在cmd（命令提示字元）中輸入就可以看到Javadoc 的用法和選項（前提是安裝配置了JDK），以下列舉Javadoc 指令的常用選項： ##- author包含@author 段-splitindex

表示套件名稱；	##sourcefiles
javadoc -help
名稱	說明
#-public	只顯示public 類別與成員
-protected	顯示protected/public 類別與成員（預設值）
-package	顯示package/protected/public 類別與成員
-private	顯示所有類別和成員
-d	輸出檔案的目標目錄
-version	包含@version 段落

將索引分成每個字母對應一個檔案

-windowtitle

文件的瀏覽器視窗標題

#用Doc產生又麻煩又慢，那還有沒有其他方法呢？

第二個：IDE工俱生成

我們可以用Eclipse或IDEA生成，Eclipse我不怎麼用，用IDEA給你們示範一下吧！

 在工具這個裡面的JavaDoc裡面，進去後是這樣的

 輸出目錄必須選擇，不然生成不了######注意了，因為Java的編碼與IDEA的編碼不一樣，所以在其他命令形參欄目裡面，要填寫以下內容###

-encoding utf8 -docencoding utf8 -charset utf8

###生成之後，是這樣的### ############ ######

以上是如何使用Java文檔註解產生文件？的詳細內容。更多資訊請關注PHP中文網其他相關文章！