java接口注释_Java的注释和API文档

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

单行注释

多行注释

文档注释

一、单行注释和多行注释

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

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

public classHelloWorld{/*这是我的第一个Java程序

*为了保持美观性

*这是多行注释*/

public static voidmain(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文档下载方法：

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 :指定一个路径，用于将生成的API文档放在指定的目录下-d . :放在当前目录下*-windowtitle ：该选项指定一个字符串，用于设置API文档的浏览器的窗口标题*-doctitle :该选项指定一个HTML格式的文本，用于指定概述网页的标题*-header:该选项指定了一个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:

packageone;/**Description:

*网站：疯狂Java联盟
>

*Copyright (C),2019-2020,A.B.C

*This program is protected by copyright laws.

*Programe Name:sample

*Date:2020/2/7

*@author Mike

*@version 2.2*/

public classTest1

{/***@paramname 该参数指定向谁打招呼

*@return返回打招呼的字符串*/

publicString hello(String name)

{return name+',你好'；

}

}

程序清单test2.java

1 *Programe Name:sample

2 *Date:2020/2/7

3 *@author Mike4 *@version 2.2

5 */

6 public classTest27 {8 /**

9 *简单测试成员变量10 */

11 public intage;12 /**

13 *Test类的测试构造器14 */

15 public intTest()16 {17

18 }19 }

为了提取到文档中的@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