1. 什么是注释？
注释（comment）。对Java程序中的代码进行文字性解释说明。不会被Java编译和运行。
2. Java注释
Java中的注释主要分为三类：
| 类型 | 语法 | 用途 |
|---|---|---|
| 单行注释 | // 注释内容 | 对代码进行简短说明，编译时忽略 |
| 多行注释 | /* 注释内容 */ | 可跨行，用于较长的解释或临时屏蔽代码块 |
| 文档注释 | /** 注释内容 */ | Java独有，用于生成API文档，可包含HTML标签和@标签 |
2.1 单行注释
//这是一个Java类
public class CommentTest {//main()方法：Java程序的主入口public static void main(String[] args) {System.out.println("Hello World!"); //这是一个打印输出语句}
}
2.2 多行注释
/*这是一个多行注释可以在这里声明多行注释的信息！1. Java中有三种注释格式：单行注释、多行注释、文档注释（Java独有）2. 单行注释、多行注释的作用：① 对程序中的代码进行解释说明。② 可以注释可能存在错误的代码，方便程序进行调试。3. 注意：① 单行注释和多行注释中声明的信息，不参与编译。即编译后生成的字节码文件中不包含注释内容。② 多行注释不能嵌套使用。
*/
public class CommentTest {public static void main(String[] args) {System.out.println("Hello World!");}
}
查看源文件被编译后的字节码文件中，单行注释和多行注释是否被编译：
- 如图所示，注释没有被Java编译器进行编译。
2.3 文档注释
Java独有。文档注释内容可以被JDK提供的文档生成工具（javadoc）解析，生成一套以网页文件（HTML）形式体现的该程序的说明文档。
1. 文档注释常用标签
| 标签 | 描述 | 适用位置 |
|---|---|---|
| @author | 作者 | 类、接口 |
| @version | 版本 | 类、接口 |
| @param | 参数说明 | 方法、构造器 |
| @return | 返回值说明 | 方法 |
| @throws / @exception | 抛出的异常 | 方法、构造器 |
| @see | 参考链接 | 任意 |
| @since | 从哪个版本开始 | 类、方法、字段 |
| @deprecated | 已过时 | 类、方法、字段 |
2. javadoc 工具的使用
示例使用的源文件CommentTest.java，内容：
/**
文档注释：
文档注释内容可以被JDK提供的javadoc工具解析，生成一套以网页文件形式体现的该程序的说明文档。@author Evan
@version 1.0
*/
public class CommentTest {public static void main(String[] args) {System.out.println("Hello World!");}
}
基本命令格式:
javadoc [选项] [包名] [源文件名]
常用选项
| 选项 | 说明 |
|---|---|
| -d <目录> | 指定生成的HTML文档存放目录 |
| -author | 包含@author信息 |
| -version | 包含@version信息 |
| -encoding | 源文件编码，如UTF-8 |
| -charset | 生成的HTML文档字符集 |
| -private | 显示所有类和成员（默认只显示public和protected） |
示例1: 为源文件生成HTML文档
-
打开cmd命令行终端，切换到源文件所在目录。
-
执行命令：
javadoc -d mydoc -encoding gbk -charset gbk -version -author CommentTest.java![image]()
-d mydoc：将生成的文档放到mydoc目录下。-author -version：在文档中显示作者和版本信息。-encoding gbk -charset gbk：指定源文件的字符编码和生成后HTML文件的字符编码。- -charset utf-8 指定生成的 HTML 文档的字符集。
- 忽略编码参数：
如果不指定-encoding时，javadoc会使用系统默认字符编码（Windows 上通常是 GBK，Linux/macOS 是 UTF-8），这样可能在跨平台时出现乱码，因此不推荐。
-
在
../mydoc/index.html即可查看生成的API文档。
示例2： 为整个包生成HTML文档
javadoc -d mydoc -author -version com.example.utils
3. 常见问题
-
使用
javadoc -encoding utf-8，出现错误: 编码utf-8的不可映射字符-
原因分析
这个错误通常是因为 源文件的实际编码 与 -encoding 指定的编码不一致导致的。javadoc 尝试用 UTF-8 读取文件，但源文件中存在不符合 UTF-8 格式的字节（比如用 GBK 保存的中文字符），于是报“不可映射字符”。 -
解决方案
确认源文件的真实编码：- 方式1：用记事本打开源文件，点击“另存为”，查看右下角的编码。
- 方式2：在 Windows 上打开cmd命令行，使用
chcp命令 查看活动代码页。
根据实际编码调整
-encoding参数，如果源文件是 GBK 编码，将命令改为：javadoc -d mydoc -encoding gbk -charset utf-8 CommentTest.java- 如果源文件是 UTF-8，但可能带有 BOM，也可以继续用 -encoding utf-8，但建议确保文件是无 BOM 的 UTF-8。
-
将源文件统一转为 UTF-8（推荐）
用文本编辑器（如 VS Code、Notepad++）将源文件另存为 UTF-8 无 BOM 格式。
之后就可以放心使用：javadoc -encoding utf-8 -charset utf-8 CommentTest.java
-
-
文档注释中的内容可以包含HTML标签（如
<p>、<code>）来格式化文本。 -
若注释中包含{@code ...}或{@literal ...}，可避免HTML转义，直接显示代码片段。
-
良好的文档注释应清晰描述功能、参数、返回值及异常，便于他人使用和维护。