Java 文档注释

Java 文档注释 (Javadoc) 深度学习笔记1. 什么是 Javadoc定义Javadoc 是 Java 官方提供的文档生成工具它通过解析源代码中的特定格式注释自动生成 HTML 格式的 API 文档。核心作用自动生成文档无需手动编写 HTML从代码中提取信息生成标准文档。代码规范强制开发者在编写代码时思考接口设计、参数含义和返回值。IDE 集成在 IntelliJ IDEA、Eclipse 等 IDE 中鼠标悬停或按CtrlQ(Windows) /CmdJ(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.2since从哪个版本开始引入since 1.8see参考链接类、方法、URLsee java.util.Listdeprecated标记为过时建议不再使用deprecated 请使用 newMethod()serial序列化字段描述serial 用户ID3.2 方法级别标签标签作用示例param描述参数必须param name 用户姓名return描述返回值必须void 方法除外return 用户对象若不存在则返回 nullthrows/exception描述抛出的异常throws IOException 当文件读取失败时see参考其他方法see #calculateTotal()deprecated标记方法过时deprecated 已废弃使用 v2 版本3.3 字段级别标签标签作用示例serial序列化字段描述serial 订单IDsee参考其他字段或类see #MAX_SIZE4. 完整代码示例importjava.io.IOException;importjava.util.List;/** * 用户管理类负责用户信息的增删改查。 * * p该类是线程安全的可以在多线程环境下使用。/p * * author 张三 * version 2.0 * since 1.8 * see java.util.ArrayList */publicclassUserManager{/** * 最大用户数量限制。 * * serial 用于序列化 */publicstaticfinalintMAX_USERS1000;privateListStringusers;/** * 初始化用户管理器。 * * param initialCapacity 初始容量必须大于 0 * throws IllegalArgumentException 如果 initialCapacity 0 */publicUserManager(intinitialCapacity){if(initialCapacity0){thrownewIllegalArgumentException(容量必须大于0);}this.usersnewjava.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 包含所有用户名的列表 */publicListStringgetUsers(){returnusers;}}5. HTML 标签支持Javadoc 注释支持标准的 HTML 标签用于格式化文本如加粗、列表、代码块等。HTML 标签作用示例p段落p这是一个段落。/pbr换行第一行br第二行b/strong加粗b重要/bi/em斜体i注意/iul,li无序列表ulli项1/li/ulol,li有序列表olli第一步/li/olcode行内代码使用 {code System.out.println}pre预格式化代码块preint 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-windowtitleMy Project API-doctitleMy Project Documentationsrc/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更是为了让阅读代码的人包括未来的你能快速理解代码意图。