【JavaSE】Java的注释全解

1. 注解简介

Java的注解分为三类：

单行注释

多行注释

文档注释

1.1 单行注释

概述：就是在程序中注释一行代码

语法：将双斜杠【//】放在需要注释的内容之前就可以了。

1.2 多行注释

概述：将程序中的多行注释一次性的注释掉

语法 ：/* 注释文字 */

1.3 文档注释

概述：文档注释就是通过JDK提供的javadoc工具吗，将源代码中的文档注释内容提取成一份程序的API文档。

语法：/** 注释文字 */

【API文档就是一个说明性的文档，用于说明每个类、每个方法的用途】

由于文档注释是用于生成API文档的，而API主要用于说明类、方法、成员变量的功能。随意javadoc工具默认只处理public或protected修饰的类、接口、方法、成员变量、构造器和内部类之间的注释。忽略其他地方的文档注释。

当然，如果想要private修饰的内容也是可以的，只需要在使用javadoc工具时增加-private选项即可。

2. javadoc命令

2.1 javadoc的使用

基本语法：javadoc选项 Java源文件|包

例如：javadoc -d apidoc -windowtitle jdkapi -doctitle API文档 -header 我的页眉 *.java

javadoc常用选项：

-d ：指定一个路径，用于将生成的API文档放到指定目录下

-windowtitle ：指定一个字符串，用于设置API文档的浏览器窗口标题

-doctitle ：指定一个HTML格式的文本，用于指定概述页面的标题

-header ：指定一个HTML格式的文本，指定每个页面的页眉

2.2 javadoc标记

@author：指定作者

@version：指定版本

@param：方法的参数信息

@return：方法的返回值信息

@exception：抛出异常的类型

@throws：抛出的异常，和@exception同义

@see：用于指定交叉参考的内容

@deprecated：不推荐使用的方法

注意：这些标记的使用是有位置限制的。且javadoc默认不会提取@author和@version这两个标记的信息，如果需要添加这两个标记的信息，需要在使用javadoc工具时指定-author和-version这两个选项。

类和接口：

@author

@version

@see

@deprecated

方法和构造器：

@param

@return

@exception

@throws

@see

@deprecated

成员变量：

@see

@deprecated