文档注释笔记

Java语言中强大的注释形式：文档注释。如果编写Java源代码时添加了合适的文档注释，然后通过Jdk提供的javadoc工具可以直接将源代码中的文档注释提取成一份系统的API文档。
[size=x-small][color=red][b]1.问题：API文档是什么？[/b][/color][/size]
开发一个大型软件时，需要定义成千上万的类，而且需要很多人参与开发。每个人都会开发一些类，并在类里定义了一些方法、属性提供给其他人使用，但其他人怎么知道如何使用这些类和方法呢？
这时候需要提供一份说明文档，用于说明每个类、每个方法的用途。当其他人使用一个类或一个方法的时候，他无需关心这个类或者方法的具体实现，他只要知道这个类或方法的功能即可，然后使用这个类或者方法来实现具体目的，也就是通过调用应用程序接口（API）来编程。[b][color=blue]API文档就是用以说明这些应用程序接口的文档。对于Java语言而言，API通常详细说明了每个类、每个方法的功能、用法等。[/color][/b]

2.文档注释、API文档、Javadoc工具
文档注释用于生成API文档，API文档主要用于说明类、方法和属性的功能。javadoc只处理源文件在类、接口、方法、属性、构造器和内部类之前的注释，忽略其他地方的注释。javadoc工具默认处理以public和protected修饰的类、接口、方法、属性、构造器之前的文档注释。[b][color=blue]如果要提取private修饰的内容，可以在使用javadoc工具时增加-private选项。[/color][/b]

3.文档注释语法：
文档注释以斜线后跟两个星号（\**），以星号后跟一个斜线（*/）作为结尾，中间部分全是文档注释，会被提取到API文档中去。

4.范例

package wang;
   /**
    * Description:
    * <br/>Copyright(C), 2011-08-04， 汪斌伟
    * <br/>这段代码为测试用途
    * <br/>ProgrameName:
    * <br/>Date:
    * @author:汪斌伟
    * @version 1.0
    */
   public class TestJavadoc {
        /**
         *简单测试属性
         */
       protected String name;
      /**
       *主方法，程序的入口
        */
       public static void main(String[] args) {
            System.out.println("测试Javadoc代码");
       }
   }

5.javadoc的基本用法：
javadoc 选项 java源文件/包
javadoc命令可对源文件、包来生成API文档，在上面的语法格式中，Java源文件可以支持通配符，例如使用*.java来代表当前路径下所有Java源文件。javadoc的常用选项：
1）-d<directory>:该选项指定一个路径，用于将生成的API文档放在指定目录下。
2）-windowtitle<text>:该选项指定一个字符串，用于设置API文档的浏览器窗口标题。
3）doctitle<html-code>:该选项指定一个HTML格式的文本，用于指定概述页面的标题。
4）-header<html-code>:该选项指定一个HTML格式的文本，包含每个页面的页眉。
想要查看其他选项可通过java -help来查看javadoc的所有选项。
[b][color=red]例：javadoc -d apidoc -windowtitle 测试 -doctitle 学习 javadoc 工具的测试API文档 -header 自定义类 Test*.java[/color][/b]

6.除此之外，如果我们希望javadoc工具生成更为详细的的文档信息，例如为方法参数、方法返回值等生成详细的说明信息，即可使用javadoc标记常用的javadoc标记：
@author：指定Java程序的作者
@version:指定源文件的版本
@deprecated:不推荐使用的方法
@param:方法参数的说明信息
@return:方法返回值的说明信息
@see:“参见",用于指定交叉参考的内容
@exception:抛出异常的类型
@throws:抛出的异常，和exception同义