Java 文檔註釋

　　Java只是三種註釋方式。前兩種分別是// 和/* */，第三種被稱做說明註釋，它以/** 開始，以 */結束。

　　說明註釋容許你在程序中嵌入關於程序的信息。你可使用javadoc工具軟件來生成信息，並輸出到HTML文件中。

　　說明註釋，是你更加方面的記錄你的程序的信息。

　　javadoc 標籤

　　javadoc工具軟件識別如下標籤：

　　標籤描述示例

　　@author標識一個類的做者@author description

　　@deprecated指名一個過時的類或成員@deprecated description

　　{@docRoot}指明當前文檔根目錄的路徑Directory Path

　　@exception標誌一個類拋出的異常@exception exception-name explanation

　　{@inheritDoc}從直接父類繼承的註釋Inherits a comment from the immediate surperclass.

　　{@link}插入一個到另外一個主題的連接{@link name text}

　　{@linkplain}插入一個到另外一個主題的連接，可是該連接顯示純文本字體Inserts an in-line link to another topic.

　　@param說明一個方法的參數@param parameter-name explanation

　　@return說明返回值類型@return explanation

　　@see指定一個到另外一個主題的連接@see anchor

　　@serial說明一個序列化屬性@serial description

　　@serialData說明經過writeObject( ) 和 writeExternal( )方法寫的數據@serialData description

　　@serialField說明一個ObjectStreamField組件@serialField name type description

　　@since標記當引入一個特定的變化時@since release

　　@throws和 @exception標籤同樣.The @throws tag has the same meaning as the @exception tag.

　　{@value}顯示常量的值，該常量必須是static屬性。Displays the value of a constant, which must be a static field.

　　@version指定類的版本@version info

　　文檔註釋

　　在開始的/**以後，第一行或幾行是關於類、變量和方法的主要描述.

　　以後，你能夠包含一個或多個何種各樣的@標籤。每個@標籤必須在一個新行的開始或者在一行的開始緊跟星號(*).

　　多個相同類型的標籤應該放成一組。例如，若是你有三個@see標籤，能夠將它們一個接一個的放在一塊兒。

　　下面是一個類的說明註釋的示例：

　　/*** This class draws a bar chart.

　　* @author Zara Ali

　　* @version 1.2

　　*/

　　javadoc輸出什麼

　　javadoc工具將你Java程序的源代碼做爲輸入，輸出一些包含你程序註釋的HTML文件。

　　每個類的信息將在獨自的HTML文件裏。javadoc也能夠輸出繼承的樹形結構和索引。

　　因爲javadoc的實現不一樣，工做也可能不一樣，你須要檢查你的Java開發系統的版本等細節，選擇合適的Javadoc版本。

　　實例

　　下面是一個使用說明註釋的簡單實例。注意每個註釋都在它描述的項目的前面。

　　在通過javadoc處理以後，SquareNum類的註釋將在SquareNum.html中找到。

　　import java.io.*;

　　/**

　　* This class demonstrates documentation comments.

　　* @author Ayan Amhed

　　* @version 1.2

　　*/

　　public class SquareNum {

　　/**

　　* This method returns the square of num.

　　* This is a multiline description. You can use

　　* as many lines as you like.

　　* @param num The value to be squared.

　　* @return num squared.

　　*/

　　public double square(double num) {

　　return num * num;

　　}

　　/**

　　* This method inputs a number from the user.

　　* @return The value input as a double.

　　* @exception IOException On input error.

　　* @see IOException

　　*/

　　public double getNumber() throws IOException {

　　InputStreamReader isr = new InputStreamReader(System.in);

　　BufferedReader inData = new BufferedReader(isr);

　　String str;

　　str = inData.readLine();

　　return (new Double(str)).doubleValue();

　　}

　　/**

　　* This method demonstrates square().

　　* @param args Unused.

　　* @return Nothing.

　　* @exception IOException On input error.

　　* @see IOException

　　*/

　　public static void main(String args[]) throws IOException

　　{

　　SquareNum ob = new SquareNum();

　　double val;

　　System.out.println("Enter value to be squared: ");

　　val = ob.getNumber();

　　val = ob.square(val);

　　System.out.println("Squared value is " + val);

　　}

　　}

　　以下，使用javadoc工具處理SquareNum.java文件：

　　$ javadoc SquareNum.java

　　Loading source file SquareNum.java...

　　Constructing Javadoc information...

　　Standard Doclet version 1.5.0_13

　　Building tree for all the packages and classes...

　　Generating SquareNum.html...

　　SquareNum.java:39: warning - @return tag cannot be used\

　　in method with void return type.

　　Generating package-frame.html...

　　Generating package-summary.html...

　　Generating package-tree.html...

　　Generating constant-values.html...

　　Building index for all the packages and classes...

　　Generating overview-tree.html...

　　Generating index-all.html...

　　Generating deprecated-list.html...

　　Building index for all classes...

　　Generating allclasses-frame.html...

　　Generating allclasses-noframe.html...

　　Generating index.html...

　　Generating help-doc.html...

　　Generating stylesheet.css...

　　1 warning

　　$

　　(編輯：雷林鵬 來源：網絡)