Java 文档注释
Java 文档注释 (Javadoc) 深度学习笔记
1. 什么是 Javadoc？
定义：
Javadoc 是 Java 官方提供的文档生成工具，它通过解析源代码中的特定格式注释，自动生成 HTML 格式的 API 文档。
核心作用：
- 自动生成文档：无需手动编写 HTML，从代码中提取信息生成标准文档。
- 代码规范：强制开发者在编写代码时思考接口设计、参数含义和返回值。
- IDE 集成：在 IntelliJ IDEA、Eclipse 等 IDE 中，鼠标悬停或按
Ctrl+Q(Windows) /Cmd+J(Mac) 可直接查看注释内容。 - 团队协作：作为团队内部的技术文档标准，降低沟通成本。
文件位置：
- 工具：
javadoc.exe(位于 JDK 的bin目录下)。 - 标准文档：JDK 自带的 API 文档（如
java.lang.String的文档）就是由 Javadoc 生成的。
2. 注释格式规范
Javadoc 注释以/**开头，以*/结尾，中间每一行通常以*开头（可选，但推荐）。
/** * 这是 Javadoc 注释的标准格式。 * 它可以包含多行文本。 * * @author 张三 * @version 1.0 */publicclassMyClass{// ...}注意：
- Javadoc 注释必须紧挨着被注释的元素（类、方法、字段等），中间不能有空行或其他代码。
- 普通的
//或/* ... */注释不会被 Javadoc 工具提取。
3. 核心标签 (Tags)
Javadoc 使用@开头的标签来定义结构化信息。
3.1 类/接口级别标签
| 标签 | 作用 | 示例 |
|---|---|---|
@author | 作者名 | @author 张三 |
@version | 版本号 | @version 1.0.2 |
@since | 从哪个版本开始引入 | @since 1.8 |
@see | 参考链接（类、方法、URL） | @see java.util.List |
@deprecated | 标记为过时，建议不再使用 | @deprecated 请使用 newMethod() |
@serial | 序列化字段描述 | @serial 用户ID |
3.2 方法级别标签
| 标签 | 作用 | 示例 |
|---|---|---|
@param | 描述参数（必须） | @param name 用户姓名 |
@return | 描述返回值（必须，void 方法除外） | @return 用户对象，若不存在则返回 null |
@throws/@exception | 描述抛出的异常 | @throws IOException 当文件读取失败时 |
@see | 参考其他方法 | @see #calculateTotal() |
@deprecated | 标记方法过时 | @deprecated 已废弃，使用 v2 版本 |
3.3 字段级别标签
| 标签 | 作用 | 示例 |
|---|---|---|
@serial | 序列化字段描述 | @serial 订单ID |
@see | 参考其他字段或类 | @see #MAX_SIZE |
4. 完整代码示例
importjava.io.IOException;importjava.util.List;/** * 用户管理类，负责用户信息的增删改查。 * * <p>该类是线程安全的，可以在多线程环境下使用。</p> * * @author 张三 * @version 2.0 * @since 1.8 * @see java.util.ArrayList */publicclassUserManager{/** * 最大用户数量限制。 * * @serial 用于序列化 */publicstaticfinalintMAX_USERS=1000;privateList<String>users;/** * 初始化用户管理器。 * * @param initialCapacity 初始容量，必须大于 0 * @throws IllegalArgumentException 如果 initialCapacity <= 0 */publicUserManager(intinitialCapacity){if(initialCapacity<=0){thrownewIllegalArgumentException("容量必须大于0");}this.users=newjava.util.ArrayList<>(initialCapacity);}/** * 添加一个新用户。 * * <p>如果用户名已存在，将抛出异常。</p> * * @param username 用户名，不能为空 * @return true 如果添加成功，false 如果用户已存在 * @throws NullPointerException 如果 username 为 null * @throws IOException 如果写入日志失败 * @see #removeUser(String) * @deprecated 请使用 {@link #addUserSafe(String)} 替代，此方法在 v3.0 移除 */@DeprecatedpublicbooleanaddUser(Stringusername)throwsIOException{// 实现逻辑returntrue;}/** * 安全添加用户（推荐方法）。 * * @param username 用户名 * @return 添加结果 */publicbooleanaddUserSafe(Stringusername){returntrue;}/** * 获取用户列表。 * * @return 包含所有用户名的列表 */publicList<String>getUsers(){returnusers;}}5. HTML 标签支持
Javadoc 注释支持标准的 HTML 标签，用于格式化文本（如加粗、列表、代码块等）。
| HTML 标签 | 作用 | 示例 |
|---|---|---|
<p> | 段落 | <p>这是一个段落。</p> |
<br> | 换行 | 第一行<br>第二行 |
<b>/<strong> | 加粗 | <b>重要</b> |
<i>/<em> | 斜体 | <i>注意</i> |
<ul>,<li> | 无序列表 | <ul><li>项1</li></ul> |
<ol>,<li> | 有序列表 | <ol><li>第一步</li></ol> |
<code> | 行内代码 | 使用 {@code System.out.println} |
<pre> | 预格式化代码块 | <pre>int x = 1;</pre> |
{@link ...} | 内联链接（推荐） | 参考 {@link java.util.List} |
{@code ...} | 内联代码（推荐） | 参数 {@code name} |
注意：
- 推荐使用
{@link}和{@code}代替<a>和<code>，因为它们能自动处理包名和转义，且生成的链接更智能。 - 避免使用复杂的 CSS 或 JavaScript。
6. 生成文档
6.1 命令行生成
在终端（CMD/PowerShell/Terminal）中，进入项目根目录：
# 基本用法javadoc-dout/docs-author-versionsrc/com/example/*.java# 参数说明：# -d <目录> : 指定输出文档的目录# -author : 包含 @author 标签# -version : 包含 @version 标签# -encoding UTF-8: 指定源文件编码（防止中文乱码）# -charset UTF-8 : 指定文档编码# -windowtitle : 设置浏览器窗口标题# -doctitle : 设置文档标题完整示例：
javadoc-d./api-docs-author-version-encodingUTF-8-charsetUTF-8-windowtitle"My Project API"-doctitle"My Project Documentation"src/com/example/**/*.java6.2 IDE 生成
- IntelliJ IDEA:
Tools->Generate JavaDoc...- 选择模块、输出目录、编码，点击 OK。
- Eclipse:
Project->Generate Javadoc...- 选择路径和选项。
7. 最佳实践与规范
7.1 内容规范
- 首句总结：第一句话应该是该元素的功能总结（Javadoc 会自动提取第一句作为摘要）。
- ✅
计算两个整数的和。 - ❌
这是一个用于计算的方法，它接收两个参数...
- ✅
- 参数描述：
@param必须描述参数的含义和约束（如“不能为 null”、“必须大于 0”）。 - 返回值：
@return必须描述返回值的含义，特别是null的含义。 - 异常：
@throws必须列出所有受检异常（Checked Exception），非受检异常（RuntimeException）可选但推荐列出。 - 示例代码：如果逻辑复杂，使用
<pre>或{@code}提供使用示例。
7.2 常见错误
- 遗漏标签：有参数没写
@param，有返回值没写@return。 - 描述模糊：
@param name 名字-> 应改为@param name 用户的真实姓名，不能为空。 - 中文乱码：生成时未指定
-encoding UTF-8。 - 注释位置错误：注释与代码之间有空行，导致不被识别。
- 过度注释：对显而易见的代码（如
getters/setters）进行冗长注释。
7.3 现代工具推荐
虽然javadoc是标准工具，但现代开发常使用更强大的工具：
- Maven Javadoc Plugin: 在构建时自动生成。
- Gradle Javadoc Task: Gradle 项目使用。
- Sphinx / Doxygen: 跨语言文档工具。
- Swagger / OpenAPI: 专门用于 RESTful API 文档（Spring Boot 常用）。
8. 特殊用法技巧
8.1 内联标签{@...}
在文本中引用其他元素或代码：
/** * 调用 {@link #addUser(String)} 添加用户。 * 参数 {@code username} 必须唯一。 * 如果失败，抛出 {@link IllegalArgumentException}。 */publicvoidregister(Stringusername){...}8.2 继承文档{@inheritDoc}
如果子类方法覆盖了父类方法，且描述与父类相同，可以使用：
@Override/** * {@inheritDoc} */publicvoiddoSomething(){...}或者完全省略注释，IDE 会自动显示父类注释。
8.3 隐藏文档
使用@hidden标签（非标准，部分工具支持）或@internal标记内部实现细节，不对外公开。
9. 总结
- Javadoc 是 Java 生态的基石，是编写高质量代码的必备技能。
- 格式严格：
/** ... */，紧挨代码，使用标准标签。 - 核心标签：
@param,@return,@throws,@author,@version。 - 生成工具：
javadoc命令行或 IDE 集成。 - 最佳实践：首句总结、描述清晰、避免乱码、使用
{@link}和{@code}。
记住：好的文档注释不仅是为了生成 HTML，更是为了让阅读代码的人（包括未来的你）能快速理解代码意图。