項目到了尾聲，大家都開(kāi)始頭疼——又要寫(xiě)文檔了……是的，我們大多數人都不是從正規的Programer訓練出來(lái)的。當初學(xué)習編程序的時(shí)候，就從來(lái)沒(méi)有想過(guò)要給自己寫(xiě)的那幾個(gè)程序編寫(xiě)一份完整的文檔，所有的注釋都僅僅是為了自己當時(shí)能夠想起這段代碼到底是干什么的，沒(méi)有人想過(guò)這些代碼的升級、共享問(wèn)題。但是，開(kāi)始做商業(yè)軟件之后，一切都變了，尤其是大型的團隊開(kāi)發(fā)項目中。 大家也許注意到了，java的API文檔總是緊緊跟隨著(zhù)JSDK的版本的提高而保持著(zhù)最新的狀態(tài)。試想一下，手工維護這么復雜的文檔可能嗎？當然不可能，這一切都是javadoc這個(gè)小程序的功勞（當然也有java類(lèi)庫作者們做程序注釋的一份功勞）。API文檔就是用它根據最新的源代碼自動(dòng)生成的，一切都是這么容易——只需要你把本來(lái)就要寫(xiě)的注釋寫(xiě)得更規范一些，再稍微詳細一些。然而，大家似乎好像根本就沒(méi)有意識到它的存在，很少有人會(huì )用它來(lái)為自己的程序生成文檔。不知道，你現在是否對它有了興趣？好吧，下面我們就開(kāi)始這個(gè)令人輕松的自動(dòng)文檔生成之旅。 【如何插入注釋】 JAVADOC為你生成代碼不是憑空來(lái)的，也不是它會(huì )自動(dòng)分析你的代碼——每個(gè)人都有自己的代碼風(fēng)格，如果要進(jìn)行分析翻譯恐怕還是機器碼更容易生成百倍。它的分析機制依賴(lài)于你按照規范為你的代碼添加應有而足夠的注釋。只有你老老實(shí)實(shí)寫(xiě)注釋?zhuān)庞锌赡馨岩郧靶枰鲭p份的工作一次做了。 Javadoc工具可以從下列對象中提取出信息： · 包。 · 公共類(lèi)。 · 公共接口。 · 公共或者受保護的方法。 · 公共或者受保護的變量/常數。 針對每一種特性，你都應該提供一條注釋。每一條注釋都要以/**打頭，以*/結尾。在每條/** …… */文檔注釋可包括任意格式的文字。，它的第一個(gè)句子應該是一個(gè)總結性的語(yǔ)句，javadoc會(huì )自動(dòng)把它提出來(lái)制作總結頁(yè)。當然，這里你完全可以使用一些HTML的記號，例如<i>...</i>表示斜體；<tt>...</tt>表示等寬的“打印機”字體；<b>...</b>表示粗體；甚至用<img...>包括一副圖象等等。（但是不要使用類(lèi)似于<h1>的標題格式的標記，或者水平分隔線(xiàn)<hr>等，它們會(huì )和文檔自己的格式發(fā)生沖突）然后在后面接上一些特殊的“標記”。每個(gè)標記以@開(kāi)頭，例如@author或者@param等等。 加入在注釋中包含了指向其它文件的其它文件的鏈接的話(huà)（例如你的插圖和圖片），需要將那些文件放置在名為doc-files的子目錄中。javadoc會(huì )將這些目錄以及其中的文件從源目錄復制到文檔目錄。下面我們分類(lèi)解釋一下我們可能會(huì )比較常用的一些標記。 ■常規注釋 下面這些標記可以在所有文檔注釋中使用。 ◇ @since 版本 該標記可以生成一個(gè)注釋表明這個(gè)特性（類(lèi)、接口、屬性或者方法等）是在軟件的哪個(gè)版本之后開(kāi)始提供的。 ◇ @deprecated 類(lèi)、屬性、方法名等 這個(gè)標記可以增加一條注釋?zhuān)赋鱿鄳念?lèi)、方法或者屬性不再應該使用。javadoc僅將首句復制到概覽部分和索引中。后面得句子還可以解釋為什么不鼓勵使用它。有時(shí)候，我們也推薦另外一種解決辦法，例如： @deprecated Use <tt>theAnotherMethod</tt> 或者使用{@link}標記給一個(gè)推薦的連接關(guān)于它的使用我們將馬上介紹。 ◇ @see 鏈接 這個(gè)標記在“See also”（參見(jiàn)）小節增加一個(gè)超鏈接。這里的鏈接可以是下面幾項內容： · package.class#member label 添加一個(gè)指向成員的錨鏈接，空格前面是超鏈接的目標，后面是顯示的文字。注意分隔類(lèi)和它的成員的是#而不是點(diǎn)號，你可以省略包名或者連類(lèi)名也一塊省略，缺省指當前的包和類(lèi)，這樣使注釋更加簡(jiǎn)潔，但是#號不能省略。label是可以省略的。 · <a href=...>label</a> 這個(gè)不用解釋了吧。 · "Text" 這個(gè)直接在“See also”中添加一段沒(méi)有鏈接的文字。 ◇ {@link 鏈接目標 顯示文字} 其實(shí)準確的說(shuō)，link的用法和see的用法是一樣，see是把鏈接單列在參見(jiàn)項里，而link是在當前的注釋中的任意位置直接嵌入一段帶超級鏈接的文字。 ■為類(lèi)和接口添加注釋 類(lèi)或者接口的注釋必須在所有import語(yǔ)句的后面，同時(shí)又要位于class定義的前面。除了上面所說(shuō)的常規標記以外，你還可以在類(lèi)注釋中使用如下標記： ◇ @author 作者名 當使用author標記時(shí)，用指定的文本文字在生成的文檔中添加“Author”（作者）項。文檔注釋可以包含多個(gè)@author標記?？梢詫γ總€(gè)@author指定一個(gè)或者多個(gè)名字。當然你同樣可以使用多個(gè)作者標記，但是它們必須放在一塊兒。 ◇ @version 版本 這個(gè)標記建議一個(gè)“版本”條目，后面的文字可以是當前版本的任意描述。 下面是類(lèi)注釋的一個(gè)例子： /** * An implementation of a menu bar. You add <code>JMenu</code> objects to the * menu bar to construct a menu. When the user selects a <code>JMenu</code> * object, its associated <code>JPopupMenu</code> is displayed, allowing the * user to select one of the <code>JMenuItems</code> on it. * <p> * For information and examples of using menu bars see * <a href="How‘ target=_blank>http://java.sun.com/docs/books/tutorial/uiswing/components/menu.html">How to Use Menus</a>, * a section in <em>The Java Tutorial.</em> * For the keyboard keys used by this component in the standard Look and * Feel (L&F) renditions, see the * <a href=doc-files/Key-Index.html#JMenuBar>JMenuBar</a> key assignments. * <p> * <strong>Warning:</strong> * Serialized objects of this class will not be compatible with * future Swing releases. The current serialization support is appropriate * for short term storage or RMI between applications running the same * version of Swing. A future release of Swing will provide support for * long term persistence. * * @beaninfo * attribute: isContainer true * description: A container for holding and displaying menus. * * @version 1.85 04/06/00 * @author Georges Saab * @author David Karlton * @author Arnaud Weber * @see JMenu * @see JPopupMenu * @see JMenuItem */ ■方法注釋 緊靠在每條方法注釋的前面，必須有一個(gè)它所描述的那個(gè)方法的簽名。同樣除了使用常規用途的標記以外，還可以使用如下針對方法的注釋?zhuān)? ◇ @param 變量描述 當前方法需要的所有參數，都需要用這個(gè)標記進(jìn)行解釋?zhuān)⑶疫@些標記都應該放在一起。具體的描述（說(shuō)明）可同時(shí)跨越多行，并且可以使用html標記。 ◇ @return 該方法的返回值 這個(gè)標記為當前方法增加一個(gè)返回值（“Returns”）小節。同樣具體描述支持html并可跨多行。 ◇ @throws 該方法拋出的異常 這個(gè)標記為當前方法在“Throws”小節添加一個(gè)條目，并會(huì )自動(dòng)創(chuàng )建一個(gè)超級鏈接。具體的描述可以跨越多行，同樣可以包括html標記。一個(gè)方法的所有throws都必須放在一起。 下面是一個(gè)方法注釋的例子： /** * Returns the model object that handles single selections. * * @param ui the new MenuBarUI L&F object * @return the <code>SingleSelectionModel</code> property * @see SingleSelectionModel * @see JComponent#getUIClassID * @see UIDefaults#getUI */ ■包和綜述注釋 前面的都是針對某一個(gè)類(lèi)、方法等的注釋?zhuān)梢灾苯臃旁贘AVA源文件中。然而為了生成一個(gè)包的注釋?zhuān)仨氃诿總€(gè)包的目錄下放置一個(gè)名為package.html的文件來(lái)對包進(jìn)行描述。標簽<body>....</body>之間的文字都會(huì )被javadoc自動(dòng)提取出來(lái)。 也可以為所有源文件提供一個(gè)綜述注釋?zhuān)瑢?xiě)入名為overview.html文件中，將其放在所有源文件所在的父目錄下面。標簽<body> .... </body>之間的文字也都會(huì )被javadoc自動(dòng)提取出來(lái)，做成文檔的Overview 【如何提取程序文檔】 首先，我們還是依照慣例來(lái)看看javadoc的基本用法，你可以通過(guò)javadoc -help來(lái)獲得它當前版本的具體設定細節。 javadoc [options] [packagename] [sourcefiles] [@files] 參數可以按造任意順序排列。 · options 命令行選項。 · packagenames 一系列包的名字，空格分隔，必須分別制定想要為之建立文檔的每一個(gè)包。Javadoc不遞歸作用于每一個(gè)包，也不允許使用通配符。 · sourcefiles 一系列源文件名，用空格分隔。源文件名可以包括路徑和通配符如“*”。 · @files 以任意次序包含包名和源文件的一個(gè)或者多個(gè)文件。當在sourcefiles中需要指定的文件太多的時(shí)候，就可以使用它來(lái)簡(jiǎn)化操作。目標文件是以空格或者回車(chē)來(lái)進(jìn)行分隔的源文件名。 其中常用的選項有： -d 路徑 指定javadoc保存生成的HTML文件的目的目錄，缺省為當前目錄。 -author 在文檔中包含作者信息（默認情況下會(huì )被省略） -version 在文檔中包含版本信息（在默認情況下會(huì )被省略） -header header文本 指定放置在每個(gè)輸出文件頂部的頁(yè)眉文件。該頁(yè)眉文件將放在上部導航欄的右邊，header文本可以包括HTML標記和空格，但是如果這樣就必須用引號將它括起。在header中的任何內部引號都不許使用轉義。 -footer footer文本 指定放置在每個(gè)輸出文件底部的腳注文本。腳本將放置在下部導航欄的右邊，其它同header一樣。 -bottom text 指定放置在么個(gè)輸出文件底部的文本。該文本將放置在頁(yè)底，位于導航欄的下面。其它同header參數。 -protected 只顯示受保護的和共有的類(lèi)及成員，這是缺省狀態(tài)。 -public 只顯示公有的類(lèi)和成員。 -package 只顯示包、受保護的和公有的類(lèi)及成員。 -private 顯示所有的類(lèi)和成員，如果是內部開(kāi)發(fā)使用的程序文檔，這個(gè)將非常有用。 -sourcepath sourcepathlist 當將包名傳遞給javadoc的時(shí)候，可以指定查找源文件（.java）的搜索路徑。但必須注意，只有當用javadoc命令指定包名時(shí)才能使用sourcepath選項。如果省略sourcepath，則javadoc使用classpath查找源文件。注意：你需要把sourcepath設置成目標包的源文件所在的目錄，例如：你在從c:jproject里有一個(gè)包c(diǎn)n.com.linuxaid，你想為它里面的文件生成文檔，那么你就必須寫(xiě)成c:jprojectcncomlinuxaid。 -clathpath clathpathlist 指定javadoc查找“引用類(lèi)”的路徑，“引用類(lèi)”是值帶文檔的類(lèi)加上它們引用的任何類(lèi)。javadoc將搜索指定路徑的所有子目錄。classpathlist可以包含多個(gè)路徑，它們用分號分隔。 下面我們來(lái)舉一個(gè)例子： 假設，我們需要在targetdocdir放置我們生成的文檔，需要對c:jproject里的cn.com.linuxaid包內的源文件建立程序文檔。那么我們需要進(jìn)入c:jprojectcncom（也就是包含了overview.html的目錄——假如你提供了它的話(huà)）。然后運行 javadoc -d targetdocdir cn.com.linuxaid 除了javadoc提供了豐富的選項參數來(lái)讓你定制你所需要生成的程序文檔以外，還可以借助doclet來(lái)產(chǎn)生任何形式的輸出，具體的情況，請仔細閱讀聯(lián)機幫助文檔。 |
聯(lián)系客服
