對(duì)于軟件工程來(lái)說(shuō)代碼的編寫(xiě)并不是重要的事情。文檔編寫(xiě)的重要性不亞于程序代碼本身。如果代碼與文檔是分離的，那么在每次修改代碼時(shí)，都需要修改相應(yīng)的文檔就會(huì)是一件相當(dāng)麻煩的事情。所以我們通過(guò)javadoc將代碼同文檔“連接”起來(lái)。
Javadoc是什么？
javadoc是Sun公司提供的一個(gè)技術(shù)，它從程序源代碼中抽取類(lèi)、方法、成員等注釋形成一個(gè)和源代碼配套的API幫助文檔。也就是說(shuō)，只要在編寫(xiě)程序時(shí)以一套特定的標(biāo)簽作注釋?zhuān)诔绦蚓帉?xiě)完成后，通過(guò)Javadoc就可以同時(shí)形式程序的開(kāi)發(fā)文檔了。
Javadoc輸出的是一些HTML文件，我們可以通過(guò)WEB瀏覽器來(lái)查看它。
Javadoc的語(yǔ)法：
所有Javadoc都只能源于/**開(kāi)始和*/結(jié)束。使用javadoc有二種方式，一種是嵌入HTML另一種是使用文檔標(biāo)簽。所謂文檔標(biāo)簽就是一些以 “@”開(kāi)頭的命令，且“@”要置于注釋行的最前面。而“行內(nèi)文檔標(biāo)簽”則可以出現(xiàn)在Javadoc注釋中的任何地方，它們也是以“@”字符開(kāi)頭，但要括在共括號(hào)內(nèi)。
Javadoc只能為public或者protected成員進(jìn)行文檔注釋。private和包內(nèi)訪問(wèn)的成員的注釋會(huì)被忽略掉。這樣做是有道理的，因?yàn)橹挥衟ublic和protected成員才能在文件之外被使用，這也體現(xiàn)了封裝性的優(yōu)點(diǎn)。
嵌入HTML:
Javadoc將HTML代碼嵌入到所生成的HTML文件中。這樣能充分利用HTML的功能。比如：
/**
*
*this is my test program;
*
*/
但一般我們不要在HTML里使用標(biāo)題，如，因?yàn)镴avadoc會(huì)插入自己的標(biāo)題，我們的標(biāo)題可能會(huì)干擾它。
一些有用的標(biāo)簽：
1)@see:引用其它類(lèi)的文檔，相當(dāng)于超鏈接，Javadoc會(huì)在其生成的HTML文件中，將@see標(biāo)簽鏈到其他的文檔
@see classname
這樣在生成的文檔中會(huì)出現(xiàn)"See Also"的超鏈蛸。但是Javadoc不去檢查你的超鏈接是否有效。
2){@link package.class#member label}
與@See的功能一樣，只是用label作主超鏈接，而不是用"see also"
3){@docRoot}：標(biāo)簽產(chǎn)生 到文檔根目錄的相對(duì)路徑，用于文檔樹(shù)頁(yè)面的顯式超鏈接
4){@inheritDoc}:標(biāo)簽從當(dāng)前這個(gè)類(lèi)的最直接的基類(lèi)中繼承相關(guān)文檔到當(dāng)前的文檔注釋中。
5)@version：使用方法為@version 2.2.1.2...
2.2.1.2...是我們作的版本說(shuō)明信息
6)@author:使用方法為 @author PowerFedora powpro@hotmail.com
也就是說(shuō)我們可以在@author后加上作者名字，email等聯(lián)系方式
7)@since：這個(gè)標(biāo)簽允許你指定程序最早使用的版本。比如我們看JDK Document里的每個(gè)類(lèi)最后都會(huì)說(shuō)明從JDK哪個(gè)版本開(kāi)始啟用。
8)@param：@param name 用于輸入客戶(hù)的姓名
@param后面是方法的參數(shù)，以及相應(yīng)的說(shuō)明
我們可以使用任意數(shù)量的此標(biāo)簽，每個(gè)參數(shù)都可以有這樣一個(gè)標(biāo)簽
9)@return this is description
@return后面是描述返回值的含義，可以延續(xù)幾行。
10)@throws fully-qualified-class-name description
fully-qualified-class-name為異常類(lèi)的完整名字，而description告訴你為什么此異常會(huì)在方法中調(diào)用出現(xiàn)。
11)@deprecated:用于指出一些舊特性已由改進(jìn)的新特性所取代，建議用戶(hù)不要再使用舊特性。
接下來(lái)我們用一個(gè)代碼將上述所有的標(biāo)簽都使用起來(lái)，看一下效果：
//: test Javadoc,JavaCode.java
import java.util.*;
/** 這是一個(gè)為了測(cè)試Javadoc而專(zhuān)門(mén)寫(xiě)的類(lèi)
* 功能是打印字符串
* @author PowerFedora
* @author powpro@hotmail.com
* @version 1.0
*/
public class JavaCode {
/** 這里的main函數(shù)，作為java程序的入口
* @param 參數(shù)為一個(gè)String對(duì)象數(shù)組
* @return 沒(méi)有返回值的內(nèi)容
* @exception exceptions 沒(méi)有異常被拋出
*/
public static void main(String[] args){
String a = "中華人民共和國(guó)";
System.out.print(a);
}
} ///:~ 值得一題的是，如果你使用eclipse的話(huà)，完全不需要背這些標(biāo)簽。當(dāng)我們?cè)谛枰⑨尩牡胤酱蛏?**之后，再打@符號(hào)eclipse會(huì)自動(dòng)顯示所支持的標(biāo)簽供我們選擇。
同樣在生成HTML文檔時(shí)我們也可以利用eclipse的export功能直接導(dǎo)出，否則用javadoc手工來(lái)生成的話(huà)是件相當(dāng)痛苦的事情。
以下列出來(lái)javadoc支持的參數(shù)：
-author
-bootclasspath
-bottom
-breakiterator
-charset
-classpath
-d
-docencoding
-docfilessubdirs
-doclet
-docletpath
-doctitle
-encoding
-exclude
-excludedocfilessubdir
-extdirs
-footer
-group
-header
-help
-helpfile
-J
-keywords
-link
-linkoffline
-linksource
-locale
-nocomment
-nodeprecated
-nodeprecatedlist
-nohelp
-noindex
-nonavbar
-noqualifier
-nosince
-notimestamp
-notree
-overview
-package
-private
-protected
-public
-quiet
-serialwarn
-source
-sourcepath
-splitindex
-stylesheetfile
-subpackages
-tag
-taglet
-tagletpath
-title
-use
-verbose
-version
-windowtitle
Javadoc是什么？
javadoc是Sun公司提供的一個(gè)技術(shù)，它從程序源代碼中抽取類(lèi)、方法、成員等注釋形成一個(gè)和源代碼配套的API幫助文檔。也就是說(shuō)，只要在編寫(xiě)程序時(shí)以一套特定的標(biāo)簽作注釋?zhuān)诔绦蚓帉?xiě)完成后，通過(guò)Javadoc就可以同時(shí)形式程序的開(kāi)發(fā)文檔了。
Javadoc輸出的是一些HTML文件，我們可以通過(guò)WEB瀏覽器來(lái)查看它。
Javadoc的語(yǔ)法：
所有Javadoc都只能源于/**開(kāi)始和*/結(jié)束。使用javadoc有二種方式，一種是嵌入HTML另一種是使用文檔標(biāo)簽。所謂文檔標(biāo)簽就是一些以 “@”開(kāi)頭的命令，且“@”要置于注釋行的最前面。而“行內(nèi)文檔標(biāo)簽”則可以出現(xiàn)在Javadoc注釋中的任何地方，它們也是以“@”字符開(kāi)頭，但要括在共括號(hào)內(nèi)。
Javadoc只能為public或者protected成員進(jìn)行文檔注釋。private和包內(nèi)訪問(wèn)的成員的注釋會(huì)被忽略掉。這樣做是有道理的，因?yàn)橹挥衟ublic和protected成員才能在文件之外被使用，這也體現(xiàn)了封裝性的優(yōu)點(diǎn)。
嵌入HTML:
Javadoc將HTML代碼嵌入到所生成的HTML文件中。這樣能充分利用HTML的功能。比如：
/**
*
*this is my test program;
*
*/
但一般我們不要在HTML里使用標(biāo)題，如，因?yàn)镴avadoc會(huì)插入自己的標(biāo)題，我們的標(biāo)題可能會(huì)干擾它。
一些有用的標(biāo)簽：
1)@see:引用其它類(lèi)的文檔，相當(dāng)于超鏈接，Javadoc會(huì)在其生成的HTML文件中，將@see標(biāo)簽鏈到其他的文檔
@see classname
這樣在生成的文檔中會(huì)出現(xiàn)"See Also"的超鏈蛸。但是Javadoc不去檢查你的超鏈接是否有效。
2){@link package.class#member label}
與@See的功能一樣，只是用label作主超鏈接，而不是用"see also"
3){@docRoot}：標(biāo)簽產(chǎn)生 到文檔根目錄的相對(duì)路徑，用于文檔樹(shù)頁(yè)面的顯式超鏈接
4){@inheritDoc}:標(biāo)簽從當(dāng)前這個(gè)類(lèi)的最直接的基類(lèi)中繼承相關(guān)文檔到當(dāng)前的文檔注釋中。
5)@version：使用方法為@version 2.2.1.2...
2.2.1.2...是我們作的版本說(shuō)明信息
6)@author:使用方法為 @author PowerFedora powpro@hotmail.com
也就是說(shuō)我們可以在@author后加上作者名字，email等聯(lián)系方式
7)@since：這個(gè)標(biāo)簽允許你指定程序最早使用的版本。比如我們看JDK Document里的每個(gè)類(lèi)最后都會(huì)說(shuō)明從JDK哪個(gè)版本開(kāi)始啟用。
8)@param：@param name 用于輸入客戶(hù)的姓名
@param后面是方法的參數(shù)，以及相應(yīng)的說(shuō)明
我們可以使用任意數(shù)量的此標(biāo)簽，每個(gè)參數(shù)都可以有這樣一個(gè)標(biāo)簽
9)@return this is description
@return后面是描述返回值的含義，可以延續(xù)幾行。
10)@throws fully-qualified-class-name description
fully-qualified-class-name為異常類(lèi)的完整名字，而description告訴你為什么此異常會(huì)在方法中調(diào)用出現(xiàn)。
11)@deprecated:用于指出一些舊特性已由改進(jìn)的新特性所取代，建議用戶(hù)不要再使用舊特性。
接下來(lái)我們用一個(gè)代碼將上述所有的標(biāo)簽都使用起來(lái)，看一下效果：
//: test Javadoc,JavaCode.java
import java.util.*;
/** 這是一個(gè)為了測(cè)試Javadoc而專(zhuān)門(mén)寫(xiě)的類(lèi)
* 功能是打印字符串
* @author PowerFedora
* @author powpro@hotmail.com
* @version 1.0
*/
public class JavaCode {
/** 這里的main函數(shù)，作為java程序的入口
* @param 參數(shù)為一個(gè)String對(duì)象數(shù)組
* @return 沒(méi)有返回值的內(nèi)容
* @exception exceptions 沒(méi)有異常被拋出
*/
public static void main(String[] args){
String a = "中華人民共和國(guó)";
System.out.print(a);
}
} ///:~ 值得一題的是，如果你使用eclipse的話(huà)，完全不需要背這些標(biāo)簽。當(dāng)我們?cè)谛枰⑨尩牡胤酱蛏?**之后，再打@符號(hào)eclipse會(huì)自動(dòng)顯示所支持的標(biāo)簽供我們選擇。
同樣在生成HTML文檔時(shí)我們也可以利用eclipse的export功能直接導(dǎo)出，否則用javadoc手工來(lái)生成的話(huà)是件相當(dāng)痛苦的事情。
以下列出來(lái)javadoc支持的參數(shù)：
-author
-bootclasspath
-bottom
-breakiterator
-charset
-classpath
-d
-docencoding
-docfilessubdirs
-doclet
-docletpath
-doctitle
-encoding
-exclude
-excludedocfilessubdir
-extdirs
-footer
-group
-header
-help
-helpfile
-J
-keywords
-link
-linkoffline
-linksource
-locale
-nocomment
-nodeprecated
-nodeprecatedlist
-nohelp
-noindex
-nonavbar
-noqualifier
-nosince
-notimestamp
-notree
-overview
-package
-private
-protected
-public
-quiet
-serialwarn
-source
-sourcepath
-splitindex
-stylesheetfile
-subpackages
-tag
-taglet
-tagletpath
-title
-use
-verbose
-version
-windowtitle