用JavaDoc生成項目文檔

項目到了尾聲，你們都開始頭疼——又要寫文檔了……是的，咱們大多數人都不是從正規的Programer訓練出來的。當初學習編程序的時候，就歷來沒有想過要給本身寫的那幾個程序編寫一份完整的文檔，全部的註釋都僅僅是爲了本身當時可以想起這段代碼究竟是幹什麼的，沒有人想過這些代碼的升級、共享問題。可是，開始作商業軟件以後，一切都變了，尤爲是大型的團隊開發項目中。
    你們也許注意到了，java的API文檔老是牢牢跟隨着JSDK的版本的提升而保持着最新的狀態。試想一下，手工維護這麼複雜的文檔可能嗎？固然不可能，這一切都是javadoc這個小程序的功勞（固然也有java類庫做者們作程序註釋的一份功勞）。API文檔就是用它根據最新的源代碼自動生成的，一切都是這麼容易——只須要你把原本就要寫的註釋寫得更規範一些，再稍微詳細一些。然而，你們彷佛好像根本就沒有意識到它的存在，不多有人會用它來爲本身的程序生成文檔。不知道，你如今是否對它有了興趣？好吧，下面咱們就開始這個使人輕鬆的自動文檔生成之旅。

      【如何插入註釋】

    JAVADOC爲你生成代碼不是憑空來的，也不是它會自動分析你的代碼——每一個人都有本身的代碼風格，若是要進行分析翻譯恐怕仍是機器碼更容易生成百倍。它的分析機制依賴於你按照規範爲你的代碼添加應有而足夠的註釋。只有你老老實實寫註釋，纔有可能把之前須要作雙份的工做一次作了。
    Javadoc工具能夠從下列對象中提取出信息：
    · 包。
    · 公共類。
    · 公共接口。
    · 公共或者受保護的方法。
    · 公共或者受保護的變量/常數。
    針對每一種特性，你都應該提供一條註釋。每一條註釋都要以/**打頭，以*/結尾。在每條/** …… */文檔註釋可包括任意格式的文字。，它的第一個句子應該是一個總結性的語句，javadoc會自動把它提出來製做總結頁。固然，這裏你徹底可使用一些HTML的記號，例如<i>...</i>表示斜體；<tt>...</tt>表示等寬的「打印機」字體；<b>...</b>表示粗體；甚至用<img...>包括一副圖象等等。（可是不要使用相似於<h1>的標題格式的標記，或者水平分隔線<hr>等，它們會和文檔本身的格式發生衝突）而後在後面接上一些特殊的「標記」。每一個標記以@開頭，例如@author或者@param等等。
    加入在註釋中包含了指向其它文件的其它文件的連接的話（例如你的插圖和圖片），須要將那些文件放置在名爲doc-files的子目錄中。javadoc會將這些目錄以及其中的文件從源目錄複製到文檔目錄。下面咱們分類解釋一下咱們可能會比較經常使用的一些標記。

    ■常規註釋
    下面這些標記能夠在全部文檔註釋中使用。
    ◇ @since 版本
    該標記能夠生成一個註釋代表這個特性（類、接口、屬性或者方法等）是在軟件的哪一個版本以後開始提供的。
    ◇ @deprecated 類、屬性、方法名等
    這個標記能夠增長一條註釋，指出相應的類、方法或者屬性再也不應該使用。javadoc僅將首句複製到概覽部分和索引中。後面得句子還能夠解釋爲何不鼓勵使用它。有時候，咱們也推薦另一種解決辦法，例如：
    @deprecated Use <tt>theAnotherMethod</tt>
    或者使用{@link}標記給一個推薦的鏈接關於它的使用咱們將立刻介紹。
    ◇ @see 連接
    這個標記在「See also」（參見）小節增長一個超連接。這裏的連接能夠是下面幾項內容：
    · package.class#member label 添加一個指向成員的錨連接，空格前面是超連接的目標，後面是顯示的文字。注意分隔類和它的成員的是#而不是點號，你能夠省略包名或者連類名也一塊省略，缺省指當前的包和類，這樣使註釋更加簡潔，可是#號不能省略。label是能夠省略的。
    · <a href=...>label</a> 這個不用解釋了吧。
    · "Text" 這個直接在「See also」中添加一段沒有連接的文字。
    ◇ {@link 連接目標 顯示文字}
    其實準確的說，link的用法和see的用法是同樣，see是把連接單列在參見項裏，而link是在當前的註釋中的任意位置直接嵌入一段帶超級連接的文字。

    ■爲類和接口添加註釋
    類或者接口的註釋必須在全部import語句的後面，同時又要位於class定義的前面。除了上面所說的常規標記之外，你還能夠在類註釋中使用以下標記：
    ◇ @author 做者名
    當使用author標記時，用指定的文本文字在生成的文檔中添加「Author」（做者）項。文檔註釋能夠包含多個@author標記。能夠對每一個@author指定一個或者多個名字。固然你一樣可使用多個做者標記，可是它們必須放在一起。
    ◇ @version 版本
    這個標記建議一個「版本」條目，後面的文字能夠是當前版本的任意描述。
    下面是類註釋的一個例子：
/**
 * 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="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
 */
    
    ■方法註釋
    緊靠在每條方法註釋的前面，必須有一個它所描述的那個方法的簽名。一樣除了使用常規用途的標記之外，還可使用以下針對方法的註釋：
    ◇ @param 變量描述
    當前方法須要的全部參數，都須要用這個標記進行解釋，而且這些標記都應該放在一塊兒。具體的描述（說明）可同時跨越多行，而且可使用html標記。
    ◇ @return 該方法的返回值
    這個標記爲當前方法增長一個返回值（「Returns」）小節。一樣具體描述支持html並可跨多行。
    ◇ @throws 該方法拋出的異常
    這個標記爲當前方法在「Throws」小節添加一個條目，並會自動建立一個超級連接。具體的描述能夠跨越多行，一樣能夠包括html標記。一個方法的全部throws都必須放在一塊兒。
    下面是一個方法註釋的例子：
    /**
     * 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
     */

    ■包和綜述註釋
    前面的都是針對某一個類、方法等的註釋，能夠直接放在JAVA源文件中。然而爲了生成一個包的註釋，必須在每一個包的目錄下放置一個名爲package.html的文件來對包進行描述。標籤<body>....</body>之間的文字都會被javadoc自動提取出來。
    也能夠爲全部源文件提供一個綜述註釋，寫入名爲overview.html文件中，將其放在全部源文件所在的父目錄下面。標籤<body> .... </body>之間的文字也都會被javadoc自動提取出來，作成文檔的Overview

     【如何提取程序文檔】

    首先，咱們仍是依照慣例來看看javadoc的基本用法，你能夠經過javadoc -help來得到它當前版本的具體設定細節。
    javadoc [options] [packagename] [sourcefiles] [@files]
    參數能夠按造任意順序排列。
    · options 命令行選項。
    · packagenames 一系列包的名字，空格分隔，必須分別制定想要爲之創建文檔的每個包。Javadoc不遞歸做用於每個包，也不容許使用通配符。
    · sourcefiles 一系列源文件名，用空格分隔。源文件名能夠包括路徑和通配符如「*」。
    · @files 以任意次序包含包名和源文件的一個或者多個文件。當在sourcefiles中須要指定的文件太多的時候，就可使用它來簡化操做。目標文件是以空格或者回車來進行分隔的源文件名。
    其中經常使用的選項有：
    -d 路徑
      指定javadoc保存生成的HTML文件的目的目錄，缺省爲當前目錄。
    -author
      在文檔中包含做者信息（默認狀況下會被省略）
    -version
      在文檔中包含版本信息（在默認狀況下會被省略）
    -header header文本
      指定放置在每一個輸出文件頂部的頁眉文件。該頁眉文件將放在上部導航欄的右邊，header文本能夠包括HTML標記和空格，可是若是這樣就必須用引號將它括起。在header中的任何內部引號都不準使用轉義。
    -footer footer文本
      指定放置在每一個輸出文件底部的腳註文本。腳本將放置在下部導航欄的右邊，其它同header同樣。
    -bottom text
      指定放置在麼個輸出文件底部的文本。該文本將放置在頁底，位於導航欄的下面。其它同header參數。
    -protected
      只顯示受保護的和共有的類及成員，這是缺省狀態。
    -public
      只顯示公有的類和成員。
    -package
      只顯示包、受保護的和公有的類及成員。
    -private
      顯示全部的類和成員，若是是內部開發使用的程序文檔，這個將很是有用。
    -sourcepath sourcepathlist
      當將包名傳遞給javadoc的時候，能夠指定查找源文件（.java）的搜索路徑。但必須注意，只有當用javadoc命令指定包名時才能使用sourcepath選項。若是省略sourcepath，則javadoc使用classpath查找源文件。注意：你須要把sourcepath設置成目標包的源文件所在的目錄，例如：你在從c:jproject裏有一個包cn.com.linuxaid，你想爲它裏面的文件生成文檔，那麼你就必須寫成c:jprojectcncomlinuxaid。
    -clathpath clathpathlist
      指定javadoc查找「引用類」的路徑，「引用類」是值帶文檔的類加上它們引用的任何類。javadoc將搜索指定路徑的全部子目錄。classpathlist能夠包含多個路徑，它們用分號分隔。

    下面咱們來舉一個例子：
    假設，咱們須要在targetdocdir放置咱們生成的文檔，須要對c:jproject裏的cn.com.linuxaid包內的源文件創建程序文檔。那麼咱們須要進入c:jprojectcncom（也就是包含了overview.html的目錄——假如你提供了它的話）。而後運行 javadoc -d targetdocdir cn.com.linuxaid

    除了javadoc提供了豐富的選項參數來讓你定製你所須要生成的程序文檔之外，還能夠藉助doclet來產生任何形式的輸出，具體的狀況，請仔細閱讀聯機幫助文檔。