Question

Java 8的Javadocs是不完整的？

省略了一些方法注释，并且从基类（例如java.util.IntSummaryStatistics toString()方法复制（错误地）方法描述，注释“从类：对象复制的描述”。

public String toString()
从班级Object
复制的说明
返回对象的字符串表示形式。在   通常，toString方法返回一个字符串   “文字表示”这个对象。结果应该是简洁的   但是信息丰富的表示形式很容易让人阅读。它   建议所有子类都覆盖此方法。

类toString的{{1}}方法返回一个   字符串，由对象所属的类的名称组成   例如，符号字符'@'和未签名字符   对象哈希码的十六进制表示。其他   单词，此方法返回一个等于值的字符串：
getClass().getName() + '@' + Integer.toHexString(hashCode())
覆盖：
     课程Object
中的
toString
返回：

对象的字符串表示。

实际的Object方法返回类特定于此的信息：

toString

而不是从Object类继承的默认值，如here所示。

Answer 1

是的，这里有几个不同的问题。

IntSummaryStatistics.toString规范有一些从Object.toString复制的文本，它会覆盖。第一部分是正确的：

返回对象的字符串表示形式。通常，toString方法返回一个“文本表示”此对象的字符串。结果应该是一个简洁但信息丰富的表示，便于人们阅读。建议所有子类都覆盖此方法。

这表示Object.toString定义的合同，并对所有子类施加了要求。

从Object.toString复制的规范的第二部分是：

类toString的{{1}}方法返回一个字符串，该字符串由对象为实例的类的名称，符号字符“@”和无符号的十六进制表示形式组成。对象的哈希码。换句话说，此方法返回一个等于值的字符串：

Object

这是正确的，但无关紧要，因为它讨论了getClass().getName() + '@' + Integer.toHexString(hashCode())规范中Object.toString的实现。在这里复制这个是不合适的。请注意，这是在谈论IntSummaryStatistics.toString的实施，而不是合同，需要覆盖才能实施。

问题是，Object.toString的doc注释中使用的javadoc {@inheritDoc}指令会复制整个内容，而实际上只需复制其中的一部分。具体来说，应该复制强加于子类的合同，但实现规范不应该是。

在JDK 8之前没有办法将它们分开，所以文本要么是手工复制（导致它变得不一致），要么使用IntSummaryStatistics.toString，这会复制不需要的东西。在JDK 8中，引入了一些新的javadoc标记，例如{@inheritDoc}（实现规范），将doc注释分成不同的部分。 @implSpec指令可以选择性地继承这些部分，而不是继承整个文档。不幸的是，在这种情况下没有使用这些标签，所以我们有一些清理工作。

新标记记录在此informational JEP中。请注意，这些标记是JDK特定的，不能（还）用于JDK之外的javadoc。

还有另一件丢失。 {@inheritDoc} doc注释在概念上分为定义子类合同的部分和定义其实现的部分。理想情况下，我们希望将合同部分复制到Object.toString文档中，并为另一部分定义IntSummaryStatistics.toString的实现。原来有，但它不可见！ IntSummaryStatistics.toString的源代码将此作为其文档注释：

IntSummaryStatistics.toString

不幸的是，文本“返回非空字符串表示形式...”没有出现在javadoc输出中。这对我来说似乎是另一个错误。 编辑：错误是注释位于@Override /** * {@inheritDoc} * * Returns a non-empty string representation of this object suitable for * debugging. The exact presentation format is unspecified and may vary * between implementations and versions. */ public String toString() { ...注释和方法声明的其余部分之间。文档注释必须在之前整个方法声明，包括注释。因此，评论看起来像，就像文档评论一样，但由于它位于错误的位置，因此它被javadoc忽略。

我已提交JDK-8080449和JDK-8080450来解决这些问题。

Answer 2

我会说你说错了，这里有问题。这个toString（）方法记录在IntSummaryStatistics javadoc页面上。它未在“从类对象派生的方法”链接中引用。所以我想说如果这个方法的行为与Object.toString（）不同，那么应该记录这种行为。

Answer 3

我不同意这称“不正确”。但它有误导性，特别是关于类Object如何实现toString()的部分，因为实际上实现与此不同。

在我看来，这部分应该没有被复制。这是误导性的，不会增加可利用的信息。

但我完全同意，这种形式的文档在某种程度上是“不正确的”，对于这样的公共API来说是不值得的。即便没有文档比这个文档更好。

Java 8中不完整的Javadoc？

3 个答案: