Eclipse中 java 註釋文件 的生成方法
阿新 • • 發佈：2019-01-10
專案到了尾聲，大家都開始頭疼——又要寫文件了……是的，我們大多數人都不是從正規的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來產生任何形式的輸出，具體的情況，請仔細閱讀聯機幫助文件。
大家也許注意到了，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來產生任何形式的輸出，具體的情況，請仔細閱讀聯機幫助文件。