JavaDoc 本身不支持自动继承重载方法的完整文档，但可通过 @link 引用主方法、自定义 {@copyDoc} 标签（需插件支持），或合理精简注释实现文档复用，兼顾可维护性与规范性。
javadoc 本身不支持自动继承重载方法的完整文档，但可通过 `@link` 引用主方法、自定义 `{@copydoc}` 标签（需插件支持），或合理精简注释实现文档复用，兼顾可维护性与规范性。
在 Java 开发中，为重载方法（overloaded methods）编写重复的 JavaDoc 不仅冗余，更违背“DRY（Don’t Repeat Yourself）”原则——一旦逻辑变更，多处文档易不同步，增加维护成本。幸运的是，虽标准 JavaDoc 工具（javadoc 命令）原生不支持跨重载方法的文档继承（如类似 {@inheritDoc} 对继承方法的支持），但我们有三种经过实践验证的高效应对策略：
✅ 方案一：使用 @link 显式引用主方法（推荐 · 零依赖 · 兼容性最佳）
这是最稳妥、无需额外工具的方案。在便捷重载方法的 JavaDoc 中，用 {@link #methodName(...)} 指向核心实现方法，并简要说明参数映射逻辑：
/**
* Formats a string with optional bold and cursive styling.
*
* @param s The string to be formatted.
* @param bold {@code true} if the string should be bold; {@code false} otherwise.
* @param cursive {@code true} if the string should be cursive; {@code false} otherwise.
* @return A formatted string (e.g., wrapped with "BOLD" or "KURSIVE" markers).
*/
public static String formatMe(String s, boolean bold, boolean cursive) {
String result = s;
if (bold) result = "BOLD" + result + "BOLD";
if (cursive) result = "KURSIVE" + result + "KURSIVE";
return result;
}
/**
* Formats an empty string with default styling (neither bold nor cursive).
*
* <p>This is a convenience overload equivalent to:
* {@link #formatMe(String, boolean, boolean) formatMe("", false, false)}.
*
* @return A formatted string (always empty, unstyled).
*/
public static String formatMe() {
return formatMe("", false, false);
}
/**
* Formats a given string with default styling (neither bold nor cursive).
*
* <p>This is a convenience overload equivalent to:
* {@link #formatMe(String, boolean, boolean) formatMe(s, false, false)}.
*
* @param s The string to be formatted (may be {@code null} or empty).
* @return A formatted string.
*/
public static String formatMe(String s) {
return formatMe(s, false, false);
}✅ 优势：JDK 自带支持，IDE（IntelliJ/VS Code）能正确解析跳转，生成的 HTML 文档中链接可点击；语义清晰，读者一眼理解调用关系。
⚠️ 注意：需手动同步 @param 和 @return 描述——例如 formatMe() 不接受 s 参数，其 JavaDoc 中就不应出现 @param s，避免误导。
✅ 方案二：自定义 {@copyDoc} 标签（进阶 · 需 Maven/Gradle 插件）
若项目规模大、重载频繁，可引入 Javadoc Copydoc Plugin 或 Dokka（Kotlin/Java 混合项目），启用类似 {@copyDoc #formatMe(String,boolean,boolean)} 的标签，自动复制主方法的描述、匹配的 @param 及 @return。
立即学习“Java免费学习笔记（深入）”；
示例（需配置插件后生效）：
/**
* {@copyDoc #formatMe(String,boolean,boolean)}
*/
public static String formatMe() {
return formatMe("", false, false);
}✅ 优势：真正消除重复，修改主方法文档即全局生效。
⚠️ 注意：需额外构建配置（如 Maven 的 maven-javadoc-plugin 自定义 <tags>），团队需统一环境；部分旧版 JDK 可能不兼容，生产环境建议充分测试。
✅ 方案三：精简注释 + 清晰命名（务实 · 最低开销）
对内部工具类或小项目，可采用“最小必要注释”策略：
- 主方法保持完整 JavaDoc；
- 重载方法仅用 1 行说明其语义差异（如 @see #formatMe(String, boolean, boolean)），省略 @param/@return（因其行为完全由主方法定义）。
/** @see #formatMe(String, boolean, boolean) — uses default {@code bold=false, cursive=false}. */
public static String formatMe(String s) { ... }✅ 优势：零配置、零学习成本，适合快速迭代场景。
⚠️ 注意：过度简化可能降低 API 可发现性，建议至少保留 @return 说明（因返回值语义一致）。
总结建议
| 场景 | 推荐方案 |
|---|---|
| 大多数企业级 Java 项目 | 方案一（@link） — 平衡规范性、兼容性与可读性 |
| Kotlin/多语言混合项目 | 方案二（Dokka + @copyDoc） — 现代化文档生态支持更好 |
| 脚手架/原型代码 | 方案三（精简注释） — 快速交付，后续再升级 |
最终目标不是“不写文档”，而是“写一次，准确复用”。选择方案时，请始终以开发者体验（阅读者能否快速理解） 和维护成本（修改是否容易遗漏） 为第一考量。
