Java的注释和API文档

Java 语言的注释一共有三种类型：

单行注释

多行注释

文档注释

一、单行注释和多行注释

　　单行注释就是在程序中注释一行代码，在 Java 语言中，将双斜线(//)放在需要注释的内容之前就可以了 :

　　多行注释是指一次性地将程序中多行代码注释掉 ， 在 Java 语言中，使用" /* "和" */"将程序中需要注释的内容包含起来， "/*"表示注释开始，而" */"表示注释结束。

public class HelloWorld{
    /*这是我的第一个Java程序
     *为了保持美观性
     *这是多行注释
    */
    public static void main(String[] args){
        //简单的单行注释
        System.out.println("Hello World");
    }
}

 二、文档注释

　　Java 语言还提供了 一 种功能更强大的注释形式 : 文档注释 。 如果编写 Java 源代码时添加了合适的文档注释，然后通过 JDK 提供的 javadoc 工具可以直接将源代码里的文档注释提取成一份系统的 API（应用程序接口）文档 。

2.1 为什么要用API文档

API文档：开发一个大型软件时，需要定义成千上万个类，而且需要很多人参与开发。每个人都会开发一些类，并在类里定义一些方法、成员变量提供给其他人使用。API（应用程序接口）文档就是用于说明每个类、方法的用途。当其他人使用一个类或方法时，无需关心这个类或方法实现细节，他只要知道这个类或方法的功能即可，然后使用这个类或方法来实现具体的目的，也即是通过调用这些应用程序接口（API）来编程。API文档就是用于说明这些程序接口的文档，对于Java语言而言，API文档通常详细地说明了每个类、方法的功能及用法。

Java提供了大量基础类，因此Oracle也为这些基础类提供了相应的API文档，用于告诉开发者如何使用这些类，以及这些类里包含的方法。

2.2 API文档下载方法：

1、登录网站：https://www.oracle.com/technetwork/java/javase/downloads/index.html

2、将页面上的滚动条向下滚动，找到" Additional Resources"部分，找到对应版本的API文档（我这里使用的时JDK 11），如下图所示：

 3、单击DOWNLOAD即可下载API文档。下载成功后得到一个jdk-11.0.5_doc-all.zip文件，解压后得到一个docs文件夹，这个文件夹的内容就是JDK文档，JDK文档不仅包含API文档，还包含JDK的其他说明文档。

2.3 生成自己的API文档

　　由于文档注释用于生成API文档，而API文档用于说明类、方法、成员变量的功能。因此，javadoc工具只处理文档源文件在类、接口、方法、成员变量、构造器和内部类之前的注释，忽略其它地方的注释。javadoc 默认只处理以public或protected修饰的类、接口、方法、成员变量、构造器和内部类之前的文档注释。如想javadoc工具可以提取private修饰的内容，则可以在使用javadoc工具时增加-private选项。

javadoc命令的基本用法：

javadoc <可选选项> java源文件或包

javadoc的常用选项：

* -d <directory>:指定一个路径，用于将生成的API文档放在指定的目录下
  -d . :放在当前目录下
*-windowtitle <text> ：该选项指定一个字符串，用于设置API文档的浏览器的窗口标题
*-doctitle <html-code>:该选项指定一个HTML格式的文本，用于指定概述网页的标题
*-header<html-code>:该选项指定了一个HTML格式的文本，包含每个页面的页眉
*-author/-version······  javadoc标记信息

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

1.@param 方法参数的说明

2.@return 对 方法返回值的说明

3.@throws 方法抛出异常的描述

4.@version模块的版本号

5.@see：“参见”，用于指定交叉参考内容

6.@deprecated标记是否过时

7.@author:指定Java程序的作者

8.@version:指定源文件的版本

9.@exception:抛出异常的类型

 下面是两个Java程序清单：

程序清单Test1.java:

package one;
/*
 *Description:
 *网站：<a href="http://www.baidu.com">疯狂Java联盟</a><br>>
 *Copyright (C),2019-2020,A.B.C<br>
 *This program is protected by copyright laws.<br>
 *Programe Name:sample<br>
 *Date:2020/2/7<br>
 *@author Mike
 *@version 2.2
 */
public class Test1
{ 

    /**
     *@param name 该参数指定向谁打招呼
     *@return 返回打招呼的字符串
     */
    public String hello(String name) 
    {
        return name+',你好'；
    }
}

程序清单test2.java

 *Programe Name:sample<br>
 *Date:2020/2/7<br>
 *@author Mike
 *@version 2.2
 */
public class  Test2
{
    /**
     *简单测试成员变量
     */
    public int age;
    /**
     *Test类的测试构造器
     */
    public int Test()
    {
        
    }
}

为了提取到文档中的@author和@version等标记信息，在使用javadoc工具时增加-author和-version两个选项。对上面两个java源文件使用以下javadoc命令：

javadoc -d apidoc -windowtitle 测试 -doctitle javadoc的语法实例 -header 我的类 -author -version Test1.java Test2.java

进入Test1.java和Test2.java所在路径，打开apidoc文件夹，打开index.html文件可以看到刚刚所生成的API文档。

 查看程序包one