Java平台最“體貼”的工具--Javadoc

虛無飄渺

Java平台最“體貼”的工具--Javadoc <<轉自賽迪網>>


在軟件項目管理過程中，如何保證程序代碼與軟件技術文檔一致可以說是最令人頭疼的一件事情了。
不管是先修改代碼，還是先修改文檔，對各種記錄的管理都是一件麻煩事。而且，二者在改動上的一致性、
實時性還很難得到保證。令人高興的是Java平台的設計者充分考慮到了這一點，他們十分"體貼"地為
Java開發者們帶來一個文檔管理工具--javadoc。

javadoc利用Java編譯程序javac對程序代碼源文件中的聲明和文檔注釋進行語法分析，並在默認情況下
生成一組HTML文檔來描述類、內部類、接口、構造函數、方法和域。不過在運行過程中，它也使用了
Java平台的環境變量classpath來確定類查找路徑。這樣當涉及類和內部類的有關描述時，是否正確地設置了
classpath變量可能會影響到javadoc命令是否可以完全成功執行。

javadoc產生的默認文件列表如下：

基本頁面文件：
calssname.html 類或者接口描述文件，一個文件對應一個類或者接口
package-summary.html 包摘要文件，一個文件對應一個包
overview-summary.html 總的摘要文件

交叉引用頁面文件：
overview-tree.html 所有包的類層次頁面
package-tree.html 某個包的類層次頁面
package-use.html 包用法頁面
class-useclassname.html 類用法頁面
deprecated-list.html 不鼓勵使用的方法的頁面
serialized-form.html 序列化頁面
index-*.html 索引文件

支持文件：
help-doc.html 幫助文件
index.html 引導頁面，是整個文檔的入口
*-frame.html 框架文件
stylesheet.css 樣式表文件
doc-files目錄 保存與HTML相關的一些雜文件。例如圖片文件等。

javadoc的命令行語法如下：
javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]
參數可以按照任意順序排列。下面分別就這些參數和相關的一些內容進行說明：

Packagenames 包列表。這個選項可以是一系列的包名（用空格隔開），例如java.lang java.lang.reflect java.awt。
不過，因為javadoc不遞歸作用於子包，不允許對包名使用通配符；所以你必須顯示地列出希望建立文檔的每一個包。

Sourcefiles 源文件列表。這個選項可以是一系列的源文件名（用空格隔開），可以使用通配符。
javadoc允許四種源文件：類源代碼文件、包描述文件、總體概述文件、其他雜文件。

◇ 類源代碼文件：類或者接口的源代碼文件。

◇ 包描述文件：每一個包都可以有自己的包描述文件。包描述文件的名稱必須是"package.html"，與包的.java文件放置在一起。
包描述文件的內容通常是使用HTML標記寫的文檔。javadoc執行時將自動尋找包描述文件。如果找到，
javadoc將首先對描述文件中之間的內容進行處理，然後把處理結果放到該包的Package Summary頁面中，
最後把包描述文件的第一句（緊靠）放到輸出的Overview summary頁面中，並在語句前面加上該包的包名。

◇ 總體概述文件：javadoc可以創建一個總體概述文件描述整個應用或者所有包。總體概述文件可以被任意命名，
也可以放置到任意位置。-overview選項可以指示總體概述文件的路徑和名稱。總體概述文件的內容是使用HTML標記寫的文檔。
javadoc在執行的時候，如果發現-overview選項，那麼它將首先對文件中之間的內容進行處理；
然後把處理後的結果放到輸出的Overview summary 頁面的底部；最後把總體概述文件中的第一句放到輸出的Overview summary頁面的頂部。

◇ 其他雜文件：這些文件通常是指與javadoc輸出的HTML文件相關的一些圖片文件、Java源代碼文件（.java）、
Java程序（.class）、Java小程序（Applets）、HTML文件。這些文件必須放在doc-files目錄中。
每一個包都可以有自己的doc-files目錄。舉個例子，你希望在java.awt.Button的HTML文檔中使用一幅按鈕的圖片（Button.gif）。
首先，你必須把圖片文件放到C:usersrcjavaawtdoc-files中；然後在Button.java文件中加入下面注釋
/**
* This button looks like this:
*
*/
@files 包含文件。為了簡化javadoc命令，你可以把需要建立文檔的文件名和包名放在一個或多個文本文件中。例如，為了簡化下面命令：
javadoc -d apidoc com.mypackage1 com.mypackage2 com.mypackage3
你可以建立一個名稱為mypackage.txt的文件，其內容如下：
com.mypackage1
com.mypackage2
com.mypackage3
然後執行下面命令即可：
javadoc -d apidoc @mypackage.txt

options
命令行選項。javadoc使用doclets（doclets是指用doclet API編寫的程序。）來確定輸出的內容和格式。
命令行選項中一部分是可用於所有doclet的通用選項，一部分是由默認的標準doclet提供的專用的選項。
下面對各自一些常用的選項分別進行介紹：

通用選項：
◇ -1.1 生成具有javadoc 1.1版本生成的文檔的外觀和功能的文檔。
不是所有的選項都可以用於-1.1選項，具體可以使用javadoc -1.1 -help察看。
◇ -help 顯示聯機幫助。
◇ -bootclasspath classpathlist 指定"根類"（通常是Java平台自帶的一些類。例如java.awt.*等）的路徑。
◇ -sourcepath sourcepathlist 指定包的源文件搜索路徑。但是必須注意，只有在javadoc命令中指定了包名的時候
才可以使用-sourcepath選項。如果指定了包名，而省略了-sourcepath，那麼javadoc使用類路徑查找源文件。
舉例說明：假定你打算為com.mypackage建立文檔，其源文件的位置是C:usersrc。那麼你可以使用下面的命令：
javadoc -sourcepath c:usersrc com.mypackage
◇ -classpath classpathlist 指定javadoc查找"引用類"的路徑。引用類是指帶文檔的類加上它們引用的任何類。
javadoc將搜索指定路徑的所有子目錄。Classpathlist可以包含多個路徑（使用;隔開）。如果省略-classpath，
則javadoc使用-sourcepath查找源文件和類文件。舉例說明：假定你打算為com.mypackage建立文檔，
其源文件的位置是C:usersrc，包依賴C:userlib中的庫。那麼你可以使用下面的命令：
javadoc -classpath c:userlib -sourcepath c:usersrc com.mypackage
◇ -overview pathfilename 告訴javadoc從pathfilename所指定的文件中獲取概述文檔，
並且把它放到輸出的概述頁面（overview-summary.html）中。其中pathfilename是相對於-sourcepath的相對路徑。
◇ -public 只顯示公共類以及成員。
◇ -protected 只顯示受保護的和公共的類以及成員。缺省選項。
◇ -package只顯示包、受保護的和公共的類以及成員。
◇ -private 顯示所有類和成員。
◇ -doclet class 指定javadoc產生輸出內容的自定義doclet類。如果忽略這個選項，javadoc將使用默認的doclet產生一系列HTML文檔。
◇ -docletpath classpathlist 與- doclet選項相關，制定自定義的doclet類文件的路徑。Classpathlist可以包含多條路徑（用;隔開）。
◇ -verbose 在javadoc運行時提供更詳細的信息。

標準doclet專用選項：
◇ -author 在生成的文檔中包含"作者"項。
◇ - d directory 指定javadoc保存生成的HTML文件的目錄。省略該選項將把文件保存在當前目錄。
Directory可以是絕對目錄，也可以是相對當前目錄的相對目錄。
◇ -version 在生成的文檔中包含"版本"項。
◇ -use 為類和包生成"use"（用法）頁面。這些頁面描述了該類和包在javadoc命令涉及的文件中被使用的情況。
例如：對於給定的類C，在C的用法頁面中將包含C的子類，類型為C的域，返回變量類型為C的方法以及在參數中有變量類型為C的方法和構造器。
◇ -splitindex 把索引文件按照字母順序分為多個文件。每一個文件對應一個字母。
◇ -windowtitle title 指定輸出的HTML文檔的標題。
◇ -header header 指定輸出的HTML文檔的頁眉文本。
◇ -footer footer 指定輸出的HTML文檔的腳註文本。
◇ -bottom text 指定輸出的HTML文檔底部的文本。
◇ - group groupheading packagepatten;packagepatten;… 在總體概述頁面中按照命令的指定方式分隔各個包。例如執行下面命令：
javadoc -group "Core Packages" "java.lang*:java.util"
-group "Extension Packages" "javax.*"
java.lang java.lang.reflect java.util java這個網址已被系統封鎖rvlet java.new
在頁面中將有如下結果：
Core Packages
java.lang
java.lang.reflect
java.util
Extension Packages
java這個網址已被系統封鎖rvlet
Other Packages
java.new
◇ - noindex 不輸出索引文件。
◇ - help 在文件的導航條中忽略help鏈接。
◇ - helpfile pathfilename 指定導航條中的help鏈接所指向的幫助文件。忽略該選項，javadoc將生成缺省的幫助文件。
◇ -stylesheetfile pathfilename 指定javadoc的HTML樣式表文件的路徑。忽略該選項，javadoc將自動產生一個樣式表文件stylesheet.css。
通過上面的介紹，我們了解了javadoc的命令行語法，下面開始介紹javadoc文檔注釋方法。
javadoc注釋以"/**"開始，以"*/"結束，裡面可以包含普通文本、HTML標記和javadoc標記。
javadoc只處理源文件中在類/接口定義、方法、域、構造器之前的注釋，忽略位於其他地方的注釋。舉例如下：
/**
*我的第一個程序--Helloworld
*@author 王鴻
*@version 1.0 2001/10/15
*/
public class myHelloworld
{
/**
*在main( )方法中使用的顯示用字符串
*@see #main(java.lang.String[])
*/
static String SDisplay;
/**
*顯示HelloWorld
*@param args 從命令行中帶入的字符串
*@return 無
*/
public static void main(String args[])
{
SDisplay = "Hello World " ;
System.out.println( SDisplay );
}
}



使用下面命令：
javadoc -private -d doc -author -version myHelloworld.java
即可以生成漂亮的關於myHelloworld.java的API文檔了。
上面例子中以@開頭的標記就是javadoc標記。在Java程序中正確使用javadoc標記是一個良好的注釋習慣，
將非常有助於javadoc自動從源代碼文件生成完整的格式化API文檔。下面就對各種標記進行詳細說明。
◇ @author name-text 指定生成文檔中的"作者"項，從JDK/SDK 1.0開始引入。name-text可以指定多個名字（使用","隔開）。文檔注釋可以包含多個類。
◇ {@docroot} 代表產生文檔的根路徑，從JDK/SDK 1.3開始引入。用法舉例如下
/**
*see the copyright
*/
假定生成文檔的根目錄是doc，上面注釋所在的文件最後生成的文件是docutilityutl.html，那麼"copyright"的鏈接會指向..copyright.html。
◇ @deprecated deprecated-text 添加注釋，表明不推薦使用該API。
◇ @exception class-name description @throw的同義標記，從JDK/SDK 1.0開始引入。
◇ {@link package.class#member label} 插入指向package.class#member的內嵌鏈接，從JDK/SDK 1.2開始引入。
舉例說明，假定注釋中有如下文檔：
/** Use the {@link #getComponentAt(int, int) getComponentAt} method. */
那麼javadoc最終生成的HTML頁面中將有如下內容

Use the getComponentAt method.
◇ @param parameter-name description 描述參數，從JDK/SDK 1.0開始引入。
◇ @return description 描述返回值，從JDK/SDK 1.0開始引入。
◇ @see reference 添加"參見"標題，其中有指向reference的鏈接或者文本項，從JDK/SDK 1.0開始引入。@see標記有三種形式，下面分別說明：
（1）、@see "string" 為"string"添加文本項，不產生鏈接。
（2）、@see Label 使用HTML標記產生鏈接
（3）、@see package.class#member Label 使用Java語言的名字package.class #member產生鏈接。
◇ @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建立數據序列和類型的文檔，從JDK/SDK 1.2開始引入。
◇ @since since-text 利用since-text內容為文檔增加"since"標題，從JDK/SDK 1.1開始引入。
◇ @throws class-name description 與@exception同義。用class-name和description為輸出文檔添加"拋出"標題，從JDK/SDK 1.2開始引入。
◇ @version version-text 添加"版權"標題，從JDK/SDK 1.0開始引入。

上面介紹了標準doclet提供的所有標記。不過，需要注意這些標記的使用是有位置限制的。
其中可以出現在類或者接口文檔注釋中的標記有：@see、{@link}、@since、@deprecated、@author、@version。
可以出現在方法或者構造器文檔注釋中的標記有：@see、{@link}、@since、@deprecated、@param、@return、@throws、@exception、@serialData。
可以出現在域文檔注釋中的有：@see、{@link}、@since、@desprecated、@serial、@serialField。

除了javadoc自身提供的標準標記以外，我們可以定制自己的標記嗎？當然可以。只需要對javadoc標準的doclet程序進行擴充即可。
實際上，利用javadoc提供的doclet API，不僅可以擴充doclet標記，甚至還可以改變javadoc的整個輸出。為了滿足需要，
你可以使javadoc輸出普通文本、XML文件等。由於擴充doclet涉及到Java編程，本文不再做深入介紹。
總之，javadoc提供了完整規範的API文檔功能。在軟件項目管理中，合理地使用javadoc不僅可以減少開發時的文檔工作量，
提高效率；而且還非常有利於將來軟件的修改和維護。