位置:首頁 > Java技術 > Java基礎教程 > Java文檔注釋

Java文檔注釋

Java支持三種類型的注釋。前兩個是//和/**/。第三類被稱為文檔注釋。它是從字符序列/*,並用*/結束。

文檔注釋允許嵌入程序的信息到程序本身。然後,可以使用javadoc工具來提取信息,並把它放到一個HTML文件。

文檔注釋使它方便地記錄程序。

javadoc標簽:

javadoc工具識彆以下標記:

標簽 描述 實例
@author Identifies the author of a class. @author description
@deprecated Specifies that a class or member is deprecated. @deprecated description
{@docRoot} Specifies the path to the root directory of the current documentation Directory Path
@exception Identifies an exception thrown by a method. @exception exception-name explanation
{@inheritDoc} Inherits a comment from the immediate superclass. Inherits a comment from the immediate surperclass.
{@link} Inserts an in-line link to another topic. {@link name text}
{@linkplain} Inserts an in-line link to another topic, but the link is displayed in a plain-text font. Inserts an in-line link to another topic.
@param Documents a method's parameter. @param parameter-name explanation
@return Documents a method's return value. @return explanation
@see Specifies a link to another topic. @see anchor
@serial Documents a default serializable field. @serial description
@serialData Documents the data written by the writeObject( ) or writeExternal( ) methods @serialData description
@serialField Documents an ObjectStreamField component. @serialField name type description
@since States the release when a specific change was introduced. @since release
@throws Same as @exception. The @throws tag has the same meaning as the @exception tag.
{@value} Displays the value of a constant, which must be a static field. Displays the value of a constant, which must be a static field.
@version Specifies the version of a class. @version info

文檔注釋:

之後開始/ **,第一行或行變得類,變量或方法的主要描述。

在此之後,可以包括一個不同的@標記以上。每一個@標記必須在開始一個新行的開頭或跟隨一個星號(*),即在一行的開頭。

同一類型的多個標簽應該被組合在一起。例如,如果有三個@標記,把它們一個接一個。

下麵是一類文檔注釋的例子:

/**
* This class draws a bar chart.
* @author Zara Ali
* @version 1.2
*/

什麼javadoc輸出?

javadoc程序需要輸入Java程序的源文件,輸出包含該程序的文檔多個HTML文件。

有關每個類信息將在其自己的HTML文件。 Java實用程序的javadoc也將輸出一個索引和一個層次樹。其他HTML文件可以生成。

由於javadoc中的不同實現可能有不同的工作,需要檢查同伴的Java開發係統特定於版本的詳細信息的說明。

例子:

下麵是一個使用文檔注釋的示例程序。請注意每個注釋前麵緊鄰,它描述了項目的方式。

由javadoc的處理後,對SquareNum類的文檔將在SquareNum.htmll。

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
$

可以檢查所有生成的文檔在這裡: SquareNum.