[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 的，因为程序是我们自己写的，一眼定真）：
