Java 8 中的 Javadoc 不完整？ [关闭]答案

【问题标题】：Incomplete Javadoc in Java 8? [closed]Java 8 中的 Javadoc 不完整？ [关闭]
【发布时间】：2015-07-26 11:46:14
【问题描述】：

Java 8 的 Javadocs 不完整吗？

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

公共字符串 toString()
从班级复制的描述：Object

返回对象的字符串表示形式。在一般来说，toString 方法返回一个字符串 “文字地表示”这个对象。结果应该是简洁的但内容丰富的表示，易于人们阅读。它建议所有子类重写此方法。

Object 类的 toString 方法返回一个由对象所属的类的名称组成的字符串例如，at-sign 字符“@”和无符号对象的哈希码的十六进制表示。其他换句话说，这个方法返回一个等于值的字符串：
getClass().getName() + '@' + Integer.toHexString(hashCode())
覆盖：

toString 在课堂上Object

返回：

对象的字符串表示形式。

实际的toString 方法返回类特定信息，如下所示：

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

而不是默认继承自Object类，如图here。

【问题讨论】：

人们可能会对此争论不休。（复制的）文档说这个方法返回“一些字符串表示”，并且只详细说明了来自 Object 类的字符串表示（并不是说可能没有为其他类返回其他字符串表示）。在任何情况下，您都应该不依赖任何特定的表示，因为这是一个可能会在以后更改的实现细节。
还有："不过，使用 Collectors.toIntStatistics() 是安全的" 但现在叫summarizingInt。
感谢您提出这个问题。它指出了 JDK 文档中的一些实际错误。
致近距离投票者：这是如何基于意见的？问题指出了一个有具体解决方案的实际问题。
让我想起了 Big Lebowski 中的“老兄”：“这只是你的意见，伙计。”不是这样。 javadocs应该说什么有一个标准，这个标准显然至少部分错误。 @Stuart_Marks 已经打开了错误，关于这是否是一个意见问题的最终决定将至少部分取决于这些错误的解决方案。

标签： java java-8 javadoc

【解决方案1】：

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

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

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

这代表了Object.toString 定义的契约，它对所有子类提出了要求。

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

Object 类的toString 方法返回一个字符串，该字符串由对象作为其实例的类的名称、at 符号字符“@”和哈希码的无符号十六进制表示形式组成。物体。换句话说，这个方法返回一个字符串等于：

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

这是正确的，但无关紧要，因为它在IntSummaryStatistics.toString 的规范中谈到了Object.toString 的实现。在这里复制这个是不合适的。请注意，这里讨论的是Object.toString 的实施，而不是需要实施覆盖的合同。

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

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

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

还有一块缺失。 Object.toString doc 注释在概念上分为定义子类合同的部分和定义其实现的部分。理想情况下，我们希望将合同部分复制到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 注释和方法声明的其余部分之间。文档注释必须在整个方法声明之前之前，包括注释。所以评论 看起来 像一个 doc 评论，但是因为它在错误的地方，它被 javadoc 忽略了。

我已经提交了 JDK-8080449 和 JDK-8080450 以涵盖这些问题。

【讨论】：

JDK-8080450 已在 JDK 9 中修复。

【解决方案2】：

我会说你是对的，这里有问题。此 toString() 方法记录在 IntSummaryStatistics javadoc 页面上。它没有在“从类对象派生的方法”链接中引用。所以我想说，如果此方法的行为与 Object.toString() 不同，则应记录该行为。

【讨论】：

谢谢！这可以报告纠正吗？
报告它，请报告他们所说的话。我可能是错的，但这对我来说似乎不对。
我看不到哪里报告了 javadoc 文档遗漏——只有一个 java 错误。你知道吗？
现在可能已经无关紧要了，因为@Stuart_Marks 已经编写了错误，但您可以针对文档输入错误。该文档是 JDK 的一部分，可能存在错误。

【解决方案3】：

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

在我看来，这部分不应该被复制。它具有误导性，并且没有添加有用的信息。

但我完全同意，这种形式的文档有点“不正确”，不适合这样的公共 API。甚至没有文档会比这个文档更好。

【讨论】：

哪一部分是正确的？这一切都无关紧要！
@Jonathan 是的，它无关紧要，具有误导性，但正确。 Object 类按照描述的方式实现 toString()。
文档应该记录方法而不是陈述正确但不相关的事实。根据您的衡量，文档也可能会说“奶牛是食草动物”并且是正确的但无关紧要。对我来说，这是一种不正确的文档形式。
我完全同意在这种情况下将文档的 form 称为“不正确”。这从邪恶的“复制和粘贴”开始......
@Jonathan 整个第一段都是正确且相关的。只有第二段不应该被包括在内。请注意，它也不应该是 Object.toString()s javadoc 的一部分，它只是一个次要的实现细节。