Java(四)——Java的文档注释（使用javadoc工具生成API文档）

Java注释

编写程序时，总要为程序添加一些注释，用以说明某段代码的作用，或者某个类的用途、某个方法的功能，以及该方法的参数及返回值的意义。

为什么要编写注释？主要有一下几个方面的考虑：
-永远不要过于相信自己的理解能力。当你思路流畅，进入编程境界时，你可能很快地实现某个功能。但在以后再次阅读这段代码时，可能会不知其所以然，因此为了时刻找回当初编程时的思路，建议编写注释。

-可读性第一，效率第二。如今软件开发愈发复杂，进行一次开发往往不是一个人的工作，需要整个团队协同作战，团队队员之间就需要互相阅读他人的代码，编写注释就是为了能让他人更好更快地理解自己所编写的代码。其次，在后期维护时，仍然可以通过注释来掌握理解程序。从某种角度来说，这同样也提高了团队开发的效率。

-代码即文档！许多人认为，在软件开发中只有像《软件需求规格说明书》等一系列软件开发规范中的word文档才是文档。其实，开发人员编写的源代码也是文档的一部分，我们要把软件里最重要的文档——源代码写规范。

程序注释是源代码的重要组成部分，一份规范的程序源代码中，注释占到了源代码1/3以上。几乎所有的编程语言都会提供添加注释的方法，一般会有单行注释、多行注释。Java语言的注释一共有三种：
-单行注释（// 之后便是单行注释）
-多行注释（/* 在这之间都是注释，可跨多行 */）
-文档注释（/** 在这之间都是文档注释 */）

Java文档注释

可以利用Javadoc工具将Java源代码中的文档注释自动转化成API文档。
javadoc命令的基本用法如下：

javadoc 选项 java源文件|包

上述语法格式中，javadoc支持通配符，比如*.java就表示当前路径下所有java文件。javadoc常用选项有如下几个：

• -d(directory):该选项指定一个路径，用于将生成的API文档放到指定目录下。
• -windowtitle(text):该选项指定一个字符串，用于设置API文档的浏览器窗口标题。
• -doctitle(html-code):该选项指定一个HTML格式的文本，用于指定概述页面的标题。
  注意：只有对处于多个包下的源文件来生成API文档时，才有概述页面。
• -header(html-code):该选项指定一个HTML格式的文本，包含每个页面的页眉。
  除此之外，javadoc命令还包含了大量其他选项，我们可以通过在命令行窗口执行javadoc -help命令来查看javadoc命令的所有选项。

---

接下来，看一个具体的例子吧：
首先，编写一个Javadoc类，包含了文档注释。

package com.star.main;
/**
 * Description:
 * This program is used to test javadoc.
 * Program Name:
 * Date:
 * @author Undergoer
 * @version 1.0
 */
public class JavadocTest {
	/**
	 * 成员变量的文档注释
	 */
	 protected String name;

	/**
	 * main方法，程序入口
	 */
	 public static void main(String[] args) {
		 System.out.println("hello");
	 }
}

其次，编写一个Test类，这个类包含了对类、构造器、成员变量的文档注释。

package com.star.test;
/**
 * Description:
 * This program is used to test javadoc.
 * Program Name:
 * Date:
 * @author star
 * @version 1.0
 */
 public class Test {
	 /**
	  * 成员变量文档注释
	  */
	  public int age;
	  /**
	   * Test类构造器的文档注释
	   */
	   public Test(){}
}

在命令行窗口执行如下命令，来为刚刚编写的两个java程序生成API文档：

javadoc -d api_doc -windowtitle 测试API -doctitle 学习javadoc -header 我的类 *Test.java

在JavadocTest.java和Test.java所在路径下执行上面命令，可以看到生成API文档的提示信息。

进入此路径，可以看到一个api_doc文件夹，该文件夹下的内容就是刚刚生成的API文档，打开index.html文件，将看到如下图所示的页面。

同样，单击该页面左下角类列表区中的某个类，可以看到该类的详细说明。

---

除此之外，如果希望javadoc工具生成更详细的文档信息，例如为方法参数、方法返回值等生成详细的说明信息，则可以利用javadoc标记。常用javadoc标记如下：

• @author：指定Java程序的作者
• @version：指定源文件的版本
• @depreated：不推荐使用的方法
• @param：方法的参数说明信息
• @return：方法的返回值说明信息
• @see：“参见”，用于指定交叉参考的内容
• @exception：抛出异常的类型
• @throws：抛出的异常，和@exception同义

---

最后一点要说明的是，API文档类似于产品的使用说明书，通常只需要介绍那些暴露的、供用户使用的部分，在java类中就是以public或protected修饰的内容，因此javadoc默认只处理public或protected修饰的内容。如果开发者确实希望可以提取private修饰的内容，则可以在命令行使用javadoc工具时增加-private选项。还有，javadoc工具只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前的文档注释，忽略其他地方的文档注释。

---