Javadoc：“方法继承自”和“方法声明于”之间的区别

Question

Java <10的JDK Java文档有一个名为“继承自方法”的部分，其中列出了在父类/接口中声明的方法。但是从Java 10开始，此部分称为“声明的方法”。

为进行比较：

• Java 8: java.lang.Number
• Java 12: java.lang.Number

它们之间是否有区别？或者这仅仅是部分名称的改变？

Answer 1

在Java 10中，选项--override-methods (detail|summary)已添加到javadoc命令中：

• Release notes
• JDK-8157000：功能请求
• JDK-8187386：跟踪对Javadoc的添加

目的是减少方法的实现或重写时的噪音，但是文档保持不变。

模式

detail模式（默认）

当您使用detail而不指定javadoc时，override-methods模式是默认模式。

它表现出以前生成文档的方式：

• 如果不重写方法，它将位于“继承自方法”部分。
• 如果某个方法被覆盖，则无论其签名或文档是否更改，该方法都将记录在“方法详细信息”下。

summary模式

• 如果某个方法被覆盖并且被更改，它将记录在“方法详细信息”下。
• 否则，它将在“声明的方法”下列出。

summary模式现在用于生成JDK文档（JDK-8189706）。

请注意，此模式当前存在错误，因为它忽略了应该记录的方法签名更改，请参见JDK-8223607。

结论

您将看到“继承自方法”或“声明于”的部分。
当比较同一类的两个文档（一个文档带有“继承自”，另一个文档带有“声明于”）时，那么一个带有“继承自”的文档可能会在“方法详细信息”下列出更多方法，而对于“声明于”第一，有些方法则在“声明于”部分中。

是的，它们之间是有区别的。

示例

例如，在java.time.temporal.ChronoUnit类中可以看到行为上的差异：

• Java 8：在“方法详细信息”下列出
• Java 12：包含在“在类java.lang.Enum中声明的方法”中；另请参见source，以验证该方法是否实际被覆盖