Java 教程

Java 控制語句

面向物件程式設計

Java 內建類

Java 檔案處理

Java 錯誤和異常

Java 多執行緒

Java 同步

Java 網路程式設計

Java 集合

Java 介面

Java 資料結構

Java 集合演算法

高階 Java

Java 雜項

Java API 和框架

Java 類參考

Java 有用資源

Java - 使用 JavaDoc 工具生成文件

上一頁
下一頁

本章主要講解 Javadoc。我們將瞭解如何使用 Javadoc 為 Java 程式碼生成有用的文件。

Java 文件可以使用 javadoc 工具生成。它目前生成 html 4.0 格式的文件。從 Java 9 開始，我們可以透過在命令列引數中使用 -html5 選項來生成 html 5 格式的文件。

什麼是 Javadoc？

Javadoc 是一個隨 JDK 提供的工具，用於從 Java 原始碼生成 HTML 格式的 Java 程式碼文件，這些原始碼需要以預定義的格式進行文件記錄。

下面是一個簡單的示例，其中 /*….*/ 內部的行是 Java 多行註釋。類似地，// 前面的行是 Java 單行註釋。

示例

/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

輸出

Hello World!

您可以在描述部分包含所需的 HTML 標籤。例如，以下示例使用 <h1>....</h1> 用於標題，<p> 用於建立段落換行符 -

示例

/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
* 
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

輸出

Hello World!

Javadoc 標籤

Javadoc 工具識別以下標籤 -

標籤 描述 語法
@author 新增類的作者。 @author name-text
{@code} 以程式碼字型顯示文字，而不將其解釋為 HTML 標記或巢狀的 javadoc 標籤。 {@code text}
{@docRoot} 表示從任何生成的頁面到生成的文件根目錄的相對路徑。 {@docRoot}
@deprecated 新增一條註釋，指示不再應使用此 API。 @deprecated deprecatedtext
@exception 在生成的文件中新增一個“Throws”小標題，其中包含類名和描述文字。 @exception class-name description
{@inheritDoc} 從最近的可繼承類或可實現介面繼承註釋。 從直接父類繼承註釋。
{@link} 插入一個內聯連結，該連結具有指向指定包、類或引用的類的成員名稱的文件的可見文字標籤。 {@link package.class#member label}
{@linkplain} 與 {@link} 相同，只是連結的標籤以純文字而不是程式碼字型顯示。 {@linkplain package.class#member label}
@param 在“引數”部分新增一個引數，該引數後跟指定的 parameter-name 和描述。 @param parameter-name description
@return 新增一個“返回值”部分，其中包含描述文字。 @return description
@see 新增一個“另請參見”標題，其中包含指向引用的連結或文字條目。 @see reference
@serial 用於預設可序列化欄位的文件註釋中。 @serial field-description | include | exclude
@serialData 記錄由 writeObject( ) 或 writeExternal( ) 方法寫入的資料。 @serialData data-description
@serialField 記錄 ObjectStreamField 元件。 @serialField field-name field-type field-description
@since 在生成的文件中新增一個“自”標題，其中包含指定的 since-text。 @since release
@throws @throws 和 @exception 標籤是同義詞。 @throws class-name description
{@value} 當 {@value} 用於靜態欄位的文件註釋中時，它會顯示該常量的值。 {@value package.class#field}
@version 當使用 -version 選項時，在生成的文件中新增一個“版本”小標題，其中包含指定的 version-text。 @version version-text

示例 - 使用舊版 Java 文件

以下程式使用了文件註釋中的一些重要標籤。您可以根據需要使用其他標籤。

有關 AddNum 類的文件將生成在 HTML 檔案 AddNum.html 中，但同時也會建立一個名為 index.html 的主檔案。

import java.io.*;

/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31
*/
public class AddNum {
   /**
   * This method is used to add two integers. This is
   * a the simplest form of a class method, just to
   * show the usage of various javadoc Tags.
   * @param numA This is the first paramter to addNum method
   * @param numB  This is the second parameter to addNum method
   * @return int This returns sum of numA and numB.
   */
   public int addNum(int numA, int numB) {
      return numA + numB;
   }

   /**
   * This is the main method which makes use of addNum method.
   * @param args Unused.
   * @return Nothing.
   * @exception IOException On input error.
   * @see IOException
   */

   public static void main(String args[]) throws IOException {
      AddNum obj = new AddNum();
      int sum = obj.addNum(10, 20);

      System.out.println("Sum of 10 and 20 is :" + sum);
   }
}

讓我們編譯並執行上述程式，這將產生以下結果 -

Sum of 10 and 20 is :30

現在，使用 javadoc 實用程式處理上述 AddNum.java 檔案，如下所示 -

$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: 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...
1 warning
$

您可以在此處檢視所有生成的文件 - AddNum。如果您使用的是 JDK 1.7，則 javadoc 不會生成很好的 stylesheet.css，因此我們建議您從 https://docs.oracle.com 下載並使用標準樣式表

示例 - 使用舊版 Java 文件

使用 -html5 標誌執行 jdk 9 的 javadoc 工具以生成新型文件。

$ javadoc -html5 AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Building index for all the packages and classes...
Standard Doclet version 21.0.2+13-LTS-58
Building tree for all the packages and classes...
Generating .\AddNum.html...
AddNum.java:32: error: invalid use of @return
   * @return Nothing.
     ^
AddNum.java:16: warning: use of default constructor, which does not provide a comment
public class AddNum {
       ^
Generating .\package-summary.html...
Generating .\package-tree.html...
Generating .\overview-tree.html...
Building index for all classes...
Generating .\allclasses-index.html...
Generating .\allpackages-index.html...
Generating .\index-all.html...
Generating .\search.html...
Generating .\index.html...
Generating .\help-doc.html...
1 error
1 warning

$

它將建立一個如下所示的文件

Documentation
列印頁面

上一頁
下一頁
廣告