Javadoc生成时方法摘要遗漏方法的原因及解决办法咨询

是否正常？ #

这是不正常的，属于JDK 8早期版本中Javadoc工具的已知bug——在处理带有不同泛型约束的重载默认方法时，错误地将第二个方法判定为第一个方法的重复实现，导致方法摘要中仅显示前者；而方法详情区域因需展示完整方法签名与实现细节，所以能正确显示两个方法。

修复方案 #

• 升级JDK版本：将JDK升级到JDK 8u20及以上版本，或直接使用JDK 9+，该bug在后续版本中已被官方修复。
• 添加明确的Javadoc注释：给未显示的<T extends File> T append(final T file)方法手动添加Javadoc注释（即使是简单的/** 向文件追加内容 */这类注释），Javadoc工具会因此正确识别该方法为独立重载，从而在方法摘要中显示。
• 临时 workaround：如果无法升级JDK且不想添加注释，可以在生成Javadoc时添加参数-Xdoclint:none，关闭文档检查来强制显示所有方法，但此方法可能会忽略其他文档问题，不推荐长期使用。

内容的提问来源于stack exchange，提问作者Jin Kwon