二. 文檔注釋的格式

1. 文檔和文檔注釋的格式化

生成的文檔是 HTML 格式，而這些 HTML 格式的標識符并不是 javadoc 加的，而是我們在寫注釋的時候?qū)懮先サ摹?span style="font-family:Arial;">
比如，需要換行時，不是敲入一個回車符，而是寫入 <br>，如果要分段，就應(yīng)該在段前寫入 <p>。
文檔注釋的正文并不是直接復(fù)制到輸出文件 (文檔的 HTML 文件)，而是讀取每一行后，刪掉前導(dǎo)的 * 號及 * 號以前的空格，再輸入到文檔的。如

/**
* This is first line. <br>
***** This is second line. <br>
This is third line.
*/


2. 文檔注釋的三部分
先舉例如下

/**
* show 方法的簡述.
* <p>show 方法的詳細說明第一行<br>
* show 方法的詳細說明第二行
* @param b true 表示顯示，false 表示隱藏
* @return 沒有返回值
*/
public void show(boolean b) {
frame.show(b);
}

第一部分是簡述。文檔中，對于屬性和方法都是先有一個列表，然后才在后面一個一個的詳細的說明
簡述部分寫在一段文檔注釋的最前面，第一個點號 (.) 之前 (包括點號)。換句話說，就是用第一個點號分隔文檔注釋，之前是簡述，之后是第二部分和第三部分。

第二部分是詳細說明部分。該部分對屬性或者方法進行詳細的說明，在格式上沒有什么特殊的要求，可以包含若干個點號。
* show 方法的簡述.
* <p>show 方法的詳細說明第一行<br>
* show 方法的詳細說明第二行

簡述也在其中。這一點要記住了

第三部分是特殊說明部分。這部分包括版本說明、參數(shù)說明、返回值說明等。
* @param b true 表示顯示，false 表示隱藏
* @return 沒有返回值

三. 使用 javadoc 標記
javadoc 標記由"@"及其后所跟的標記類型和專用注釋引用組成
javadoc 標記有如下一些：
@author 標明開發(fā)該類模塊的作者
@version 標明該類模塊的版本
@see 參考轉(zhuǎn)向，也就是相關(guān)主題
@param 對方法中某參數(shù)的說明
@return 對方法返回值的說明
@exception 對方法可能拋出的異常進行說明

@author 作者名
@version 版本號
其中，@author 可以多次使用，以指明多個作者，生成的文檔中每個作者之間使用逗號 (,) 隔開。@version 也可以使用多次，只有第一次有效

使用 @param、@return 和 @exception 說明方法
這三個標記都是只用于方法的。@param 描述方法的參數(shù)，@return 描述方法的返回值，@exception 描述方法可能拋出的異常。它們的句法如下：
@param 參數(shù)名參數(shù)說明
@return 返回值說明
@exception 異常類名說明


四. javadoc 命令
用法：
　　javadoc [options] [packagenames] [sourcefiles]

選項：

-public 僅顯示 public 類和成員
-protected 顯示 protected/public 類和成員 (缺省)
-package 顯示 package/protected/public 類和成員
-private 顯示所有類和成員
-d <directory> 輸出文件的目標目錄
-version 包含 @version 段
-author 包含 @author 段
-splitindex 將索引分為每個字母對應(yīng)一個文件
-windowtitle <text> 文檔的瀏覽器窗口標題

javadoc 編譯文檔時可以給定包列表，也可以給出源程序文件列表。例如在 CLASSPATH 下有兩個包若干類如下：

　　fancy.Editor
　　fancy.Test
　　fancy.editor.ECommand
　　fancy.editor.EDocument
　　fancy.editor.EView

可以直接編譯類：
javadoc fancy\Test.java fancy\Editor.java fancy\editor\ECommand.java fancy\editor\EDocument.java fancy\editor\EView.java

也可以是給出包名作為編譯參數(shù)，如：javadoc fancy fancy.editor
可以自己看看這兩種方法的區(qū)別

到此為止javadoc就簡單介紹完了，想要用好她還是要多用，多參考標準java代碼(可參考JDK安裝目錄下的src源文件包)