【Java學習筆記之十八】Javadoc注釋的用法

Javadoc注釋的用法

Java 文檔

// 注釋一行

/* ...... */ 注釋若幹行

/** ...... */ 注釋若幹行，并寫入 javadoc 文檔

通常這種注釋的多行寫法如下：

/**

* .........

*/

javadoc -d 文檔存放目錄 -author -version 源檔案名.java

這條指令編譯一個名為"源檔案名.java"的 java 源檔案，并将生成的文檔存放在"文檔存放目錄"指定的目錄下，生成的文檔中 index.html 就是文檔的首頁。-author 和 -version 兩個選項可以省略。

二. 文檔注釋的格式

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

生成的文檔是 HTML 格式，而這些 HTML 格式的辨別符并不是 javadoc 加的，而是我們在寫注釋的時候寫上去的。

比如，需要換行時，不是敲入一個回車符，而是寫入 <br>，如果要分段，就應該在段前寫入 <p>。

文檔注釋的正文并不是直接複制到輸出檔案 (文檔的 HTML 檔案)，而是讀取每一行後，删掉前導的 * 号及 * 号以前的空格，再輸入到文檔的。如

* 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);

}

第一部分是簡述。文檔中，對于屬性和方法都是先有一個清單，然後才在後面一個一個的詳細的說明

簡述部分寫在一段文檔注釋的最前面，第一個點号 (.) 之前 (包括點号)。換句話說，就是用第一個點号分隔文檔注釋，之前是簡述，之後是第二部分和第三部分。

第二部分是詳細說明部分。該部分對屬性或者方法進行詳細的說明，在格式上沒有什麼特殊的要求，可以包含若幹個點号。

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

第三部分是特殊說明部分。這部分包括版本說明、參數說明、傳回值說明等。

三. 使用 javadoc 标記

javadoc 标記由"@"及其後所跟的标記類型和專用注釋引用組成

javadoc 标記有如下一些：

@author 标明開發該類子產品的作者

@version 标明該類子產品的版本

@see 參考轉向，也就是相關主題

@param 對方法中某參數的說明

@return 對方法傳回值的說明

@exception 對方法可能抛出的異常進行說明

@author 作者名

@version 版本号

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

使用 @param、@return 和 @exception 說明方法

這三個标記都是隻用于方法的。@param 描述方法的參數，@return 描述方法的傳回值，@exception 描述方法可能抛出的異常。它們的句法如下：

@param 參數名參數說明

@return 傳回值說明

@exception 異常類名說明

四. javadoc 指令

用法：

　　javadoc [options] [packagenames] [sourcefiles]

選項：

-public 僅顯示 public 類和成員

-protected 顯示 protected/public 類和成員 (預設)

-package 顯示 package/protected/public 類和成員

-private 顯示所有類和成員

-d <directory> 輸出檔案的目标目錄

-version 包含 @version 段

-author 包含 @author 段

-splitindex 将索引分為每個字母對應一個檔案

-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

也可以是給出包名作為編譯參數，如：javadoc fancy fancy.editor

可以自己看看這兩種方法的差別

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