從零開始學習Java編程（三）－－文檔注釋

Java語言提供了一種功能更強大的注釋形式：文檔注釋。如果編寫Java源代碼時添加了合適的文檔注釋，然后通過JDK提供的javadoc工具可以直接將源代碼里的文檔注釋提取成一份系統的API文檔。API是應用程序接口的意思，API是Java提供的基本編程接口，當使用Java語言進行編程時，不可能把所有的Java類、所有方法全部記下來，那么如果我們遇到一個不確定的地方時，必須通過API文檔來查看某個類、某個方法的功能和用法。

Java API文檔的下載地址：http://www.oracle.com/technetwork/java/javase/downloads/index.html

下載完成之后，打開DOCS/api文件夾里面的index.html文件，

1、API文檔首頁如圖

   

2、類說明區格局如下圖

   

    

  由於只有以public或protected修飾的內容才是希望暴露給別人使用的內容，而API文檔主要是向使用者提供信息，因此javadoc工具默認只處理public或protected修飾的內容。如果開發者確實希望javadoc工具可以提取private修飾的內容，則可以在使用javadoc工具時增加-private選項來實現

下面我們通過一個演示程序來說明文檔注釋

package Gee;
/**
 網站:<a href="http://www.geeit.me/">作者博客站</a>
 <br/>這是一個javadoc工具演示的程序
 <br/>程序名：javadoc演示程序
 <br/>程序文件名:JavaDocDemo
 @author Gee
 @version 1.0
 */
 public class JavaDocDemo
 {
      /**  簡單的測試Field
      */
      protected String name;
      /** 主方法，程序的入口 */
      public static void main(String[] args)
      {
              System.out.println("Hello World!");
      }
 }

除此之外，如果我們希望 javadoc工具生成更詳細的文檔信息，例如為方法參數、方法返回值等生成詳細的說明信息，則可利用javadoc標記。常用的javadoc標記如下。

  @author:指定程序的作者  

  @version:源文件的版本

  @deprecated:不推薦使用的方法

  @param:方法的參數說明信息

  @return:方法的返回值說明信息

  @see: “參見”用於指定交叉參考的內容

  @exception:拋出異常的類型

  @throws:拋出的異常,和exception同義。

javadoc工具默認不會提取@author和@version兩個標記信息，如果需要提取這兩個標記應該使用javadoc工具指定的-author和－version兩個版本

今天文檔注釋先到這里吧！