Posted on 2007-01-18 11:24
冰浪 閱讀(1195)
評(píng)論(0) 編輯 收藏 所屬分類:
Java
J2SE5中的javadoc.exe的命令行可選參數(shù)多達(dá)五十余個(gè)，其復(fù)雜性可想而知，是不是看著頭都大了呢？但通常情況下，我們不想那么麻煩！
假設(shè)源代碼在 C:\src 目錄下，其中 com.liigo 是主包，其下可能有數(shù)十個(gè)子包，數(shù)百（千）個(gè)Java文件。目錄結(jié)構(gòu)大約是這樣的：
- C:\
????| src\
??????| com\
????????| liigo\
???????????| ***
怎么才能以最簡捷的方式生成所有的API文檔呢？
c:\>
c:\>cd src
c:\src>javadoc -d doc -subpackages com.liigo
這樣就搞定了，最終生成的API文檔位于 c:\src\doc 目錄（該目錄是由javadoc.exe自動(dòng)生成的）。
上面的用法利用了“當(dāng)前目錄”和“相對(duì)路徑”，當(dāng)然也可以用絕對(duì)路徑：
...>javadoc -d c:\doc -sourcepath c:\src -subpackages com.liigo
最終生成的API文檔位于 c:\doc 目錄（該目錄同樣是由javadoc.exe自動(dòng)生成的）。
總結(jié)一下：
我們只用到了javadoc的三個(gè)參數(shù)： -d，-subpackages，-sourcepath，其中：
參數(shù) 說明
-d 指定API文檔的輸出目錄，默認(rèn)是當(dāng)前目錄。建議總是指定該參數(shù)。
-sourcepath 指定源代碼路徑，默認(rèn)是當(dāng)前目錄。 此參數(shù)通常是必須的。
-subpackages 以遞歸的方式處理各子包。關(guān)鍵參數(shù)！如果不使用本參數(shù)，每次只能處理一個(gè)子包（或需手工列出所有子包）。
注：以上示例要求 javadoc.exe 所在路徑位于系統(tǒng)環(huán)境變量“PATH”中。
補(bǔ)充一點(diǎn)：
使用參數(shù) -author 可以將作者信息（@author ***）導(dǎo)出到最終生成的API文檔中， -version 可以生成版本信息。如果是自己寫的一個(gè)包，千萬不要忘了用 -author 哦:)
最終完整的命令行是：
...>javadoc -d c:\doc -sourcepath c:\src -subpackages com.liigo -author -version
javadoc的命令行語法如下：
javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]
參數(shù)可以按照任意順序排列。下面分別就這些參數(shù)和相關(guān)的一些內(nèi)容進(jìn)行說明：
-
Packagenames 包列表。這個(gè)選項(xiàng)可以是一系列的包名（用空格隔開），例如java.lang java.lang.reflect
java.awt。不過，因?yàn)閖avadoc不遞歸作用于子包，不允許對(duì)包名使用通配符；所以你必須顯示地列出希望建立文檔的每一個(gè)包。
-
Sourcefiles 源文件列表。這個(gè)選項(xiàng)可以是一系列的源文件名（用空格隔開），可以使用通配符。javadoc允許四種源文件：類源代碼文件、包描述文件、總體概述文件、其他雜文件。
◇ 類源代碼文件：類或者接口的源代碼文件。
◇ 包描述文件：每一個(gè)包都可以有自己的包描述文件。包描述文件的名稱必須是"package.html"，與包的.java文件放置在一起。包描述文件的內(nèi)容通常是使用HTML標(biāo)記寫的文檔。javadoc執(zhí)行時(shí)將自動(dòng)尋找包描述文件。如果找到，javadoc將首先對(duì)描述文件中<body></body>之間的內(nèi)容進(jìn)行處理，然后把處理結(jié)果放到該包的Package
Summary頁面中，最后把包描述文件的第一句（緊靠<body>）放到輸出的Overview summary頁面中，并在語句前面加上該包的包名。
◇ 總體概述文件：javadoc可以創(chuàng)建一個(gè)總體概述文件描述整個(gè)應(yīng)用或者所有包?？傮w概述文件可以被任意命名，也可以放置到任意位置。-overview選項(xiàng)可以指示總體概述文件的路徑和名稱?？傮w概述文件的內(nèi)容是使用HTML標(biāo)記寫的文檔。javadoc在執(zhí)行的時(shí)候，如果發(fā)現(xiàn)-overview選項(xiàng)，那么它將首先對(duì)文件中<body></body>之間的內(nèi)容進(jìn)行處理；然后把處理后的結(jié)果放到輸出的Overview
summary 頁面的底部；最后把總體概述文件中的第一句放到輸出的Overview summary頁面的頂部。
◇ 其他雜文件：這些文件通常是指與javadoc輸出的HTML文件相關(guān)的一些圖片文件、Java源代碼文件（.java）、Java程序（.class）、Java小程序（Applets）、HTML文件。這些文件必須放在doc-files目錄中。每一個(gè)包都可以有自己的doc-files目錄。舉個(gè)例子，你希望在java.awt.Button的HTML文檔中使用一幅按鈕的圖片（Button.gif）。首先，你必須把圖片文件放到C:\user\src\java\awt\doc-files\中；然后在Button.java文件中加入下面注釋
/**
* This button looks like this:
* <img src="doc-files/Button.gif">
*/
-
@files 包含文件。為了簡化javadoc命令，你可以把需要建立文檔的文件名和包名放在一個(gè)或多個(gè)文本文件中。例如，為了簡化下面命令：
javadoc -d apidoc com.mypackage1 com.mypackage2 com.mypackage3
你可以建立一個(gè)名稱為mypackage.txt的文件，其內(nèi)容如下：
com.mypackage1
com.mypackage2
com.mypackage3
然后執(zhí)行下面命令即可：
javadoc -d apidoc @mypackage.txt
-
options 命令行選項(xiàng)。javadoc使用doclets（doclets是指用doclet API編寫的程序。）來確定輸出的內(nèi)容和格式。命令行選項(xiàng)中一部分是可用于所有doclet的通用選項(xiàng)，一部分是由默認(rèn)的標(biāo)準(zhǔn)doclet提供的專用的選項(xiàng)。下面對(duì)各自一些常用的選項(xiàng)分別進(jìn)行介紹：
通用選項(xiàng)：
◇ -1.1 生成具有javadoc 1.1版本生成的文檔的外觀和功能的文檔。不是所有的選項(xiàng)都可以用于-1.1選項(xiàng)，具體可以使用javadoc
-1.1 -help察看。
◇ -help 顯示聯(lián)機(jī)幫助。
◇ -bootclasspath classpathlist 指定"根類"（通常是Java平臺(tái)自帶的一些類。例如java.awt.*等）的路徑。
◇ -sourcepath sourcepathlist 指定包的源文件搜索路徑。但是必須注意，只有在javadoc命令中指定了包名的時(shí)候才可以使用-sourcepath選項(xiàng)。如果指定了包名，而省略了-sourcepath，那么javadoc使用類路徑查找源文件。舉例說明：假定你打算為com.mypackage建立文檔，其源文件的位置是C:\user\src。那么你可以使用下面的命令：
javadoc -sourcepath c:\user\src com.mypackage
◇ -classpath classpathlist 指定javadoc查找"引用類"的路徑。引用類是指帶文檔的類加上它們引用的任何類。javadoc將搜索指定路徑的所有子目錄。Classpathlist可以包含多個(gè)路徑（使用;隔開）。如果省略-classpath，則javadoc使用-sourcepath查找源文件和類文件。舉例說明：假定你打算為com.mypackage建立文檔，其源文件的位置是C:\user\src，包依賴C:\user\lib中的庫。那么你可以使用下面的命令：
javadoc -classpath c:\user\lib -sourcepath c:\user\src com.mypackage
◇ -overview path\filename 告訴javadoc從path\filename所指定的文件中獲取概述文檔，并且把它放到輸出的概述頁面（overview-summary.html）中。其中path\filename是相對(duì)于-sourcepath的相對(duì)路徑。
◇ -public 只顯示公共類以及成員。
◇ -protected 只顯示受保護(hù)的和公共的類以及成員。缺省選項(xiàng)。
◇ -package只顯示包、受保護(hù)的和公共的類以及成員。
◇ -private 顯示所有類和成員。
◇ -doclet class 指定javadoc產(chǎn)生輸出內(nèi)容的自定義doclet類。如果忽略這個(gè)選項(xiàng)，javadoc將使用默認(rèn)的doclet產(chǎn)生一系列HTML文檔。
◇ -docletpath classpathlist 與- doclet選項(xiàng)相關(guān)，制定自定義的doclet類文件的路徑。Classpathlist可以包含多條路徑（用;隔開）。
◇ -verbose 在javadoc運(yùn)行時(shí)提供更詳細(xì)的信息。
標(biāo)準(zhǔn)doclet專用選項(xiàng)：
◇ -author 在生成的文檔中包含"作者"項(xiàng)。
◇ - d directory 指定javadoc保存生成的HTML文件的目錄。省略該選項(xiàng)將把文件保存在當(dāng)前目錄。Directory可以是絕對(duì)目錄，也可以是相對(duì)當(dāng)前目錄的相對(duì)目錄。
◇ -version 在生成的文檔中包含"版本"項(xiàng)。
◇ -use 為類和包生成"use"（用法）頁面。這些頁面描述了該類和包在javadoc命令涉及的文件中被使用的情況。例如：對(duì)于給定的類C，在C的用法頁面中將包含C的子類，類型為C的域，返回變量類型為C的方法以及在參數(shù)中有變量類型為C的方法和構(gòu)造器。
◇ -splitindex 把索引文件按照字母順序分為多個(gè)文件。每一個(gè)文件對(duì)應(yīng)一個(gè)字母。
◇ -windowtitle title 指定輸出的HTML文檔的標(biāo)題。
◇ -header header 指定輸出的HTML文檔的頁眉文本。
◇ -footer footer 指定輸出的HTML文檔的腳注文本。
◇ -bottom text 指定輸出的HTML文檔底部的文本。
◇ - group groupheading packagepatten;packagepatten;… 在總體概述頁面中按照命令的指定方式分隔各個(gè)包。例如執(zhí)行下面命令：
javadoc -group "Core Packages" "java.lang*:java.util"
-group "Extension Packages" "javax.*"
java.lang java.lang.reflect java.util javax.servlet java.new
在頁面中將有如下結(jié)果：
Core Packages
java.lang
java.lang.reflect
java.util
Extension Packages
javax.servlet
Other Packages
java.new
◇ - noindex 不輸出索引文件。
◇ - help 在文件的導(dǎo)航條中忽略help鏈接。
◇ - helpfile path\filename 指定導(dǎo)航條中的help鏈接所指向的幫助文件。忽略該選項(xiàng)，javadoc將生成缺省的幫助文件。
◇ -stylesheetfile path\filename 指定javadoc的HTML樣式表文件的路徑。忽略該選項(xiàng)，javadoc將自動(dòng)產(chǎn)生一個(gè)樣式表文件stylesheet.css。
通過上面的介紹，我們了解了javadoc的命令行語法，下面開始介紹javadoc文檔注釋方法。
javadoc注釋以"/**"開始，以"*/"結(jié)束，里面可以包含普通文本、HTML標(biāo)記和javadoc標(biāo)記。javadoc只處理源文件中在類/接口定義、方法、域、構(gòu)造器之前的注釋，忽略位于其他地方的注釋。舉例如下：
/**
*我的第一個(gè)程序--<b>Helloworld</b>
*@author 王鴻
*@version 1.0 2001/10/15
*/
public class myHelloworld
{
/**
*在main( )方法中使用的顯示用字符串
*@see #main(java.lang.String[])
*/
static String SDisp
使用下面命令：
javadoc -private -d doc -author -version myHelloworld.java
即可以生成漂亮的關(guān)于myHelloworld.java的API文檔了。
上面例子中以@開頭的標(biāo)記就是javadoc標(biāo)記。在Java程序中正確使用javadoc標(biāo)記是一個(gè)良好的注釋習(xí)慣，將非常有助于javadoc自動(dòng)從源代碼文件生成完整的格式化API文檔。下面就對(duì)各種標(biāo)記進(jìn)行詳細(xì)說明。
◇ @author name-text 指定生成文檔中的"作者"項(xiàng)，從JDK/SDK 1.0開始引入。name-text可以指定多個(gè)名字（使用","隔開）。文檔注釋可以包含多個(gè)類。
◇ {@docroot} 代表產(chǎn)生文檔的根路徑，從JDK/SDK 1.3開始引入。用法舉例如下
/**
*see the <a href={@docroot}/copyright.html>copyright</a>
*/
假定生成文檔的根目錄是doc，上面注釋所在的文件最后生成的文件是doc\utility\utl.html，那么"copyright"的鏈接會(huì)指向..\copyright.html。
◇ @deprecated deprecated-text 添加注釋，表明不推薦使用該API。
◇ @exception class-name description @throw的同義標(biāo)記，從JDK/SDK 1.0開始引入。
◇ {@link package.class#member label} 插入指向package.class#member的內(nèi)嵌鏈接，從JDK/SDK
1.2開始引入。舉例說明，假定注釋中有如下文檔：
/** Use the {@link #getComponentAt(int, int) getComponentAt} method. */
那么javadoc最終生成的HTML頁面中將有如下內(nèi)容
Use the <a href = "Component.html#getComponentAt(int,int)"
> getComponentAt </a> method.
◇ @param parameter-name description 描述參數(shù)，從JDK/SDK 1.0開始引入。
◇ @return description 描述返回值，從JDK/SDK 1.0開始引入。
◇ @see reference 添加"參見"標(biāo)題，其中有指向reference的鏈接或者文本項(xiàng)，從JDK/SDK
1.0開始引入。@see標(biāo)記有三種形式，下面分別說明：
（1）、@see "string" 為"string"添加文本項(xiàng)，不產(chǎn)生鏈接。
（2）、@see <a href="URL#Value">Label</a> 使用HTML標(biāo)記產(chǎn)生鏈接
（3）、@see package.class#member Label 使用Java語言的名字package.class #member產(chǎn)生鏈接。
◇ @serial field-description 用于缺省可序列化域的注釋，從JDK/SDK 1.2開始引入。
◇ @serialField field-name field-type field-description 建立Serializable類的serialPersistentFields成員的ObjectStreamField組件的文檔，從JDK/SDK
1.2開始引入。
◇ @serialData data-description data-description建立數(shù)據(jù)序列和類型的文檔，從JDK/SDK
1.2開始引入。
◇ @since since-text 利用since-text內(nèi)容為文檔增加"since"標(biāo)題，從JDK/SDK
1.1開始引入。
◇ @throws class-name description 與@exception同義。用class-name和description為輸出文檔添加"拋出"標(biāo)題，從JDK/SDK
1.2開始引入。
◇ @version version-text 添加"版權(quán)"標(biāo)題，從JDK/SDK 1.0開始引入。
上面介紹了標(biāo)準(zhǔn)doclet提供的所有標(biāo)記。不過，需要注意這些標(biāo)記的使用是有位置限制的。其中可以出現(xiàn)在類或者接口文檔注釋中的標(biāo)記有：@see、{@link}、@since、@deprecated、@author、@version?？梢猿霈F(xiàn)在方法或者構(gòu)造器文檔注釋中的標(biāo)記有：@see、{@link}、@since、@deprecated、@param、@return、@throws、@exception、@serialData?？梢猿霈F(xiàn)在域文檔注釋中的有：@see、{@link}、@since、@desprecated、@serial、@serialField。
除了javadoc自身提供的標(biāo)準(zhǔn)標(biāo)記以外，我們可以定制自己的標(biāo)記嗎？當(dāng)然可以。只需要對(duì)javadoc標(biāo)準(zhǔn)的doclet程序進(jìn)行擴(kuò)充即可。實(shí)際上，利用javadoc提供的doclet
API，不僅可以擴(kuò)充doclet標(biāo)記，甚至還可以改變javadoc的整個(gè)輸出。為了滿足需要，你可以使javadoc輸出普通文本、XML文件等。由于擴(kuò)充doclet涉及到Java編程，本文不再做深入介紹。
總之，javadoc提供了完整規(guī)范的API文檔功能。在軟件項(xiàng)目管理中，合理地使用javadoc不僅可以減少
開發(fā)
時(shí)的文檔工作量，提高效率；而且還非常有利于將來軟件的修改和維護(hù)。