Javadoc注释语法与标签使用全解析

Javadoc 是 Java 官方推荐的 API 文档生成利器，其核心在于用规范的 /**...*/ 文档注释包裹代码说明，并精准使用 @param、@return、@throws 等标签来定义方法契约——参数含义、返回值语义、异常场景一目了然；同时，@see 提供关联跳转、@since 明确版本兼容性、@deprecated 清晰标注弃用方案，让生成的 HTML 文档不仅结构严谨、信息完整，更具备专业级可读性与维护性，是每位 Java 开发者提升代码质量与团队协作效率不可或缺的实践技能。

Javadoc 是 Java 提供的标准文档生成工具，通过特殊格式的注释（即文档注释）可自动生成 HTML 格式的 API 文档。关键在于使用 /** ... */ 包裹注释，并在其中合理使用标签（tags），才能让生成的文档结构清晰、信息完整。

基础语法：必须用 /** 开头，不能混用普通多行注释

只有以 /** 开始、*/ 结束的注释块才会被 Javadoc 工具识别为文档注释。普通多行注释 /* ... */ 或单行注释 // 不会被处理。

• ✅ 正确：/** 这是 Javadoc 注释 */
• ❌ 错误：/* 这不是 Javadoc 注释 */ 或 /** 这里写错了 * /（末尾空格或斜杠方向错误）
• 注释首行可空，但推荐顶格写 /**，后续行以 * 开头对齐，提升可读性

@param 标签：说明方法参数含义与约束

用于描述方法或构造器的每个参数，必须紧跟在方法文档注释中，且参数名需与代码中完全一致（区分大小写）。

• 格式：@param 参数名 描述文字
• 一个参数对应一个 @param，多个参数就写多行
• 建议说明取值范围、是否允许 null、常见用途等，例如：
  @param timeout 超时时间（毫秒），必须大于 0，传入负数将抛出 IllegalArgumentException

@return 和 @throws 标签：明确方法契约的关键

@return 描述返回值的含义和类型（若方法有返回值）；@throws 列出所有显式声明抛出的受检异常（checked exception），也可补充运行时异常（unchecked）的触发条件。

• @return 只能出现一次，放在 @param 之后、@throws 之前
• @throws IOException 表示该方法声明抛出此异常；若想说明为何抛出，可接续文字：
  @throws SecurityException 当当前线程无文件读取权限时抛出
• 未在方法签名中声明的 RuntimeException，如 NullPointerException，也可用 @throws 注明（属良好实践）

@see、@since、@deprecated 等常用补充标签

这些标签增强文档的可维护性和上下文提示：

• @see 类名 或 @see #methodName()：添加跳转链接，指向相关类或方法（支持全限定名或相对名）
• @since 1.8：标明该元素自哪个 JDK 版本起可用，便于版本兼容性判断
• @deprecated：标记已弃用的类、方法或字段；建议紧接着写替代方案，例如：
  @deprecated 使用 {@link #newMethod()} 代替
• 注意：@deprecated 是独立标签，不带参数；补充说明需另起一行或紧随其后（无空格）

好了，本文到此结束，带大家了解了《Javadoc注释语法与标签使用全解析》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！