[Java · 初窥门径] Java 注释符

🌟 想系统化学习 Java 编程？看看这个：[编程基础] Java · 学习手册

0x01：Java 注释符简介

在编写程序时，为了使代码易于理解，通常会为代码加一些注释。Java 注释就是用通俗易懂的语言对代码进行描述或解释，以达到快速、准确地理解代码的目的。

Java 注释只在 Java 源文件中有效，在编译程序时编译器会忽略这些注释，不会将其编译到字节码文件中。Java 中的注释有以下 3 种类型：

• 单行注释： 单行注释符使用 // 开头，// 后面的单行内容均为注释。

• 多行注释： 多行注释以 /* 开头以 */ 结尾，在 /* 和 */ 之间的内容均为注释。我们也可以使用多行注释为行内进行注释，但是在使用时要注意，多行注释不能嵌套使用。

• 文档注释： 文档注释以 /** 开头以 */ 结尾，注释中包含一些说明性文字以及一些 JavaDoc 标签，这些标签可以生成对应的 API。

0x02：Java 单行注释

单行注释符使用 // 开头，// 后面的单行内容均为注释。

单行注释仅对所在行有效，当编译器遇到单行注释时，会忽略该行之后的内容。单行注释主要用于解释某段代码的作用，阐明一些逻辑或算法，此外，它也常用于临时屏蔽某段代码以检验其它部分的功能。

单行注释的示例如下：

public class HelloWorld {public static void main(String[] args) {    // main 是 Java 程序的入口System.out.println("hello world");      // 打印 hello world}
}

0x03：Java 多行注释

多行注释以 /* 开头以 */ 结尾，在 /* 和 */ 之间的内容均为注释内容。 我们可以使用多行注释为单行内容进行注释，但是使用时需要注意，多行注释不能嵌套使用。

多行注释一般用于对多行代码进行详细的说明，或者临时屏蔽某个代码块的执行，示例如下：

public class HelloWorld {/*这是一个多行注释我能跨行注释哦~~~~~~~*/public static void main(String[] args) {    System.out.println("hello world");      }
}

0x04：Java 文档注释

文档注释以 /** 开头以 */ 结尾，注释符中包含一些说明性的文字以及一些 JavaDoc 标签，可以生成对应的 API。

文档注释是一种特殊的多行注释，由一对 /** 和 */ 标识，用于生成 Java API 文档。它通常出现在类、方法、属性等元素的定义前，为这些元素提供详细的描述、参数说明、返回值说明等信息。通过 javadoc 工具，我摸嗯可以从带有文档注释的代码中自动生成文档。

常用的 JavaDoc 标签如下：

标签	描述
@author	标识作者
@deprecated	标识过期的类或成员
@exception	标识抛出的异常
@param	标识方法的参数
@return	标识方法的返回值
@see	标识指定参数的内容
@serial	标识反序列化属性
@version	标识版本
@throws	标识引入一个特定的变化

文档注释一般放在类的前面或者方法的前面，看下面这个示例：

/*** 文档注释，一般放在类、方法、属性前面* @author Blue17* @version 1.0*/
public class HelloWorld {/*** 这是一个 main 方法，这是程序的入口* @param args 方法的参数*/public static void main(String[] args) {System.out.println("hello world"); }
​/*** 这是一个普通的 eat 方法，功能: 演示 xx 岁的 xxx 要干饭* @param name 干饭人的姓名* @param age 干饭年龄*/public void eat(String name, int age) {System.out.println("关注注释，不用关注这个方法的具体咋写，后面会讲解");}
}

0x05：Java 注释提取

在上面一小节中我们编写了一个文档注释的案例，那么本小节，我们尝试使用 javadoc 从中提取出注释内容。

0x0501：修改文档编码格式

如下图，我们当前文档的编码是 UTF-8 我们要将其换成 GBK（不然生成 API 文档的时候会报错 - MayBe？）：

点击 “另存为”，选择 “ANSI” 编码：

0x0502：使用 javadoc 生成 API 文档

在 Java 代码所在目录打开 CMD 窗口（之前已经教过了哈），然后运行下面这个命令：

javadoc -d MyAPI -author -version HelloWorld.java
​
# -d <存放目录> => 指定存放文档的目录名
# -author、-version => 生成的 API 文档中要展示这两个关键字

0x0503：查看生成的 API 文档

进入 javadoc 创建的 MyAPI 文件夹中，找到 index.html 文件，双击打开：

如下，这个就是 javadoc 生成的 API 文档（界面还是非常 Nice 的，因为程序是我们自己写的，一眼定真）：