JavaDoc 本身不支持自动继承或共享多签名方法的文档，但可通过 @link 引用主方法、自定义 {@copyDoc} 标签或合理精简注释实现高效复用，避免重复撰写且保持文档一致性。
javadoc 本身不支持自动继承或共享多签名方法的文档，但可通过 `@link` 引用主方法、自定义 `{@copydoc}` 标签或合理精简注释实现高效复用，避免重复撰写且保持文档一致性。
在 Java 开发中，为重载方法（overloaded methods）编写清晰、一致且可维护的 JavaDoc 是良好 API 设计的重要环节。当存在一个核心实现方法（如三参数版 formatMe(String, boolean, boolean)）和多个便利重载（如无参、单参版本）时，直接复制粘贴完整文档不仅冗余，更易导致后续维护脱节——一旦主逻辑变更，所有副本都需同步更新，风险高、成本大。
✅ 推荐方案一：使用 @link 显式引用主方法（标准、可靠、零依赖）
这是最符合 JavaDoc 规范且无需额外工具的方案。通过 {@link #methodName(ParamTypes...)} 在重载方法的文档中明确指向主方法，并补充调用细节：
/**
* Formats a string with optional 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 with applied styles.
*/
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 (not bold, not cursive).
*
* <p>This is a convenience overload that delegates to
* {@link #formatMe(String, boolean, boolean)} with arguments {@code "", false, false}.
*
* @return A formatted empty string.
*/
public static String formatMe() {
return formatMe("", false, false);
}
/**
* Formats the given string with default styling (not bold, not cursive).
*
* <p>This is a convenience overload that delegates to
* {@link #formatMe(String, boolean, boolean)} with arguments {@code s, false, false}.
*
* @param s The string to be formatted.
* @return A formatted string.
*/
public static String formatMe(String s) {
return formatMe(s, false, false);
}✅ 优势：完全兼容 JDK 自带 javadoc 工具；生成的 HTML 文档中链接可点击跳转；语义清晰，体现“委托关系”。
⚠️ 注意：需手动维护参数说明与调用逻辑的一致性，但相比全文复制，修改成本显著降低。
✅ 推荐方案二：使用 {@inheritDoc} 扩展（需第三方插件支持）
标准 JavaDoc 的 {@inheritDoc} 仅适用于继承场景（子类覆写父类方法），不支持重载方法间的文档复用。但可通过 JDK-8200512 提出的增强思路，或借助开源工具如 Javadoc Copydoc Plugin 实现类似效果：
/**
* {@copyDoc #formatMe(String,boolean,boolean)}
*/
public static String formatMe() {
return formatMe("", false, false);
}该插件会自动提取目标方法的 @param（匹配当前签名）、@return 和主描述，并注入当前文档中。需在构建流程中集成 Maven 插件并启用自定义标签解析。
立即学习“Java免费学习笔记（深入）”；
✅ 优势：真正“零重复”，主文档更新后所有引用自动同步。
⚠️ 注意：引入外部依赖，需团队统一配置；部分 IDE 可能无法实时渲染该标签，影响编写体验。
⚠️ 不推荐方案：全文复制 + 手动维护
尽管答案中提到“我本人常用复制粘贴再编辑”，但在中大型项目或对外 SDK 中，此做法极易引发文档漂移（doc drift）：例如主方法新增了对 null 输入的处理逻辑，但重载方法的 JavaDoc 未同步更新，将误导使用者。
? 最佳实践总结
- 优先采用 @link 方式：简洁、标准、可读性强，明确表达“此方法是某主方法的简化调用”；
- 重载方法的 JavaDoc 应聚焦“差异”：说明默认参数值、适用场景（如“用于快速格式化空字符串”）、以及与主方法的调用关系；
- 避免空 JavaDoc 或 `/ */` 占位**：即使内容简短，也应提供至少一行说明，否则 Javadoc 工具可能忽略该方法或产生警告；
- 保持参数命名与类型一致性：确保 @param s 在所有重载中含义一致，避免歧义（如 s 在单参版中是输入，在无参版中隐含为空字符串）。
通过以上方式，你既能遵守 JavaDoc 规范，又能大幅提升文档的可维护性与专业度——让 API 的“说明书”真正成为开发者信赖的权威来源。
