从零开始学习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两个版本

今天文档注释先到这里吧！