Java 文件注釋

Java 語言支持三種注釋形式：

這個指導(dǎo)是關(guān)于解釋 Javadoc 的。我們將看到我們怎樣能利用 Javadoc 來為我們的 Java 代碼生成有用的文件。

什么是 Javadoc？

Javadoc 是 JDK 附帶的一個工具，它被用來生成從需要預(yù)定義格式的文檔的 Java 源代碼至 HTML 格式的 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!");
    }
}

你可以將需要的 HTML 標(biāo)簽包括在描述部分內(nèi)，比如，下面的例子利用 \<h1>...\</h1> 來定義頭部和 \<p> 被用來創(chuàng)建段落間隔：

/**
* <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!");
    }
}

Javadoc 標(biāo)簽

Javadoc 標(biāo)簽是 Javadoc 認(rèn)可的關(guān)鍵字，它定義了下面信息的類型。

Javadoc 工具認(rèn)可下面的標(biāo)簽：

示例

下面的程序使用一些重要的標(biāo)簽來做文檔注釋。你可以基于你的需求利用其它的標(biāo)簽。

關(guān)于 AddNum 類的文檔將由 HTML 文件 AddNum.html 創(chuàng)建，但是同時一個名為 index.html 的主文件也將被創(chuàng)建。

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

現(xiàn)在，處理使用 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 不生成 stysheet.css，所以我建議從 http://docs.oracle.com/javase/7/docs/api/stylesheet.css 下載并使用標(biāo)準(zhǔn)的 stylesheet。