Java 8中的Javadoc不完整？

Question

Java 8的Javadocs不完整吗？一些方法注释被省略了，而且方法描述从基类中复制（不正确），例如java.util.IntSummaryStatistics toString()方法中的注释带有“从类复制的描述：Object”。实际上，toString方法返回类特定信息，如下所示：

IntSummaryStatistics{count=10, sum=129, min=2, average=12.900000, max=29}

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

- Jonathan

---

有人可能会对此提出争论。 （复制的）文档显示该方法返回“某些字符串表示”，并仅详细说明了来自Object类的字符串表示（并未说其他类可能不会返回其他字符串表示）。无论如何，您应该不要依赖于任何特定的表示形式，因为这是一个实现细节，稍后可能会更改。 - Marco13

还有一个提示："然而，使用Collectors.toIntStatistics()是安全的"。但现在它被称为summarizingInt。 - Alexis C.

我同意这个问题应该被解决。感谢您指出这一点。+1 - Fabian Barney

感谢您提出这个问题。它指出了JDK文档中的一些实际错误。 - Stuart Marks

关闭投票者：这个问题有什么是基于观点的吗？该问题指出了一个实际存在并且具有具体解决方案的问题。 - Stuart Marks

这让我想起了《大镖客》中的"The Dude"： "那只是你的看法，伙计。" 这并不意味着它就是正确的。有一个标准来规定javadocs应该说什么，而这个标准显然至少部分是错误的。@Stuart_Marks已经提出了错误报告，最终决定是否属于观点问题将在一定程度上取决于这些错误报告的解决方案。 - Steve Cohen

Answer 1

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

IntSummaryStatistics.toString规范中复制了一些文本来自Object.toString，它覆盖了Object.toString。第一部分是正确的：

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

这代表了Object.toString定义的契约，并对所有子类施加要求。

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

对象的toString方法返回一个字符串，该字符串由对象是其实例的类的名称、at-sign字符“@”和对象的哈希码的无符号十六进制表示组成。换句话说，该方法返回一个等于以下值的字符串：

getClass().getName() + '@' + Integer.toHexString(hashCode())

这是正确的，但与此无关，因为它谈论了在IntSummaryStatistics.toString规范中实现Object.toString。将其复制到这里是不合适的。请注意，这是关于Object.toString的实现而不是覆盖所需实现的契约。

问题在于javadoc {@inheritDoc}指令在IntSummaryStatistics.toString的文档注释中使用时会复制整个内容，而实际上只需要复制部分内容。具体来说，应该复制施加于子类的契约，但不应复制实现规范。

在JDK 8之前，没有办法将它们分开，因此要么手动复制（导致不一致），要么使用{@inheritDoc}，它会复制不需要的内容。在JDK 8中，引入了一些新的javadoc标签，例如@implSpec（实现规范），将文档注释分成不同的部分。 {@inheritDoc}指令可以有选择地继承这些部分，而不是继承整个文档。不幸的是，在这种情况下没有使用这些标签，因此我们需要进行一些清理。

这些新标签在此信息性JEP中有记录。请注意，这些标签是特定于JDK的，不能（尚未）用于JDK之外的javadoc。

还有一部分缺失。 Object.toString 文档注释在概念上分为定义子类契约的部分和定义其实现的部分。理想情况下，我们希望将契约部分复制到 IntSummaryStatistics.toString 的文档中，并且还有另一部分定义 IntSummaryStatistics.toString 的实现。事实证明确实有这样的部分，但它并不可见！IntSummaryStatistics.toString 的源代码具有以下文档注释：

@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输出中没有出现。这对我来说似乎是另一个错误。编辑：错误在于注释位于@Override注释和方法声明的其余部分之间。文档注释必须出现在整个方法声明之前，包括注解。因此，该注释看起来像是文档注释，但由于位置错误，被javadoc忽略了。

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

- Stuart Marks

---

JDK-8080450已在JDK 9中修复。 - Stuart Marks

Answer 2

我认为你说得没错，这里肯定有些问题。IntSummaryStatistics类中的toString()方法已在javadoc页面上有所记录，但它并未被列在“从Object类继承而来的方法”链接中。因此，如果这个方法的行为与Object.toString()不同，则应该对其进行说明。

- Steve Cohen

---

谢谢！可以报告并进行更正吗？ - Jonathan

报告它并请回报他们的回复。我可能错了，但这对我来说似乎不正确。 - Steve Cohen

我没有看到有关Javadoc文档遗漏的报告，只有Java错误。你知道吗？ - Jonathan

现在可能不太相关了，因为@Stuart_Marks已经写好了这些bug，但是你确实可以针对文档提交BUG。文档是JDK的一部分，它也可能存在BUG。 - Steve Cohen

Answer 3

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

在我看来，这部分内容不应该被复制。它是误导性的，没有提供有用的信息。

但我完全同意，这种文档形式有点“不正确”，对于这样一个公共API来说是不值得的。即使没有文档，也比这个文档更好。

- Fabian Barney

---

哪部分是正确的？这一切都不相关！ - Jonathan

@Jonathan 是的，这是无关紧要和误导性的，但是正确的。类Object按照所描述的方式实现了toString()方法。 - Fabian Barney

@Jonathan 整个第一段都是正确和相关的。只有第二段不应该被包括在内。请注意，它也不应该成为 Object.toString() 的 javadoc 的一部分，这只是一个次要的实现细节。 - biziclop

@biziclop 第一段仅适用于Object类，它为开发人员提供了指导，以便以类特定的方式覆盖toString。在一个返回统计信息逗号分隔列表的类中，它是不相关的。 - Jonathan

@Jonathan 因为它“返回对象的字符串表示形式。通常，toString方法返回一个文本上表示此对象的字符串。结果应该是简洁但信息丰富的表示，易于人阅读。”这就是你需要知道的全部内容。 - biziclop