Java 8 中的 Java 文档不完整？

Question

JavaJava8 的文档是否不完整？

一些方法注释被省略，方法描述是从基础 class 复制（错误地）（例如带有注释 "Description copied from class: Object" 的 java.util.IntSummaryStatistics toString() 方法）。

public String toString()
Description copied from class: Object

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character '@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:
getClass().getName() + '@' + Integer.toHexString(hashCode())
Overrides:

toString in class Object

Returns:

a string representation of the object.

实际toString方法returnsclass具体信息如下：

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

而不是默认继承自class对象，如图here.

Answer 1

我会说你是对的，这里有问题。此 toString() 方法记录在 IntSummaryStatistics javadoc 页面上。它未在 "Methods derived from class Object" link 中引用。所以我想说，如果此方法的行为与 Object.toString() 不同，则应记录该行为。

Answer 2

我不同意这样称呼 "incorrect"。但它具有误导性，尤其是关于 class Object 如何实现 toString() 的部分，因为实际上实现与

不同。

这部分我觉得应该没有抄袭。它具有误导性，并且没有添加可利用的信息。

但我完全同意这种形式的文档有点 "incorrect" 并且不值得这样 public API。即使没有文档也比这个文档更好。

Answer 3

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

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

Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method.

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

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

The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character '@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of:

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

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

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

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

新标签记录在此 informational 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() { ...

遗憾的是文本 "Returns a non-empty string representation..." 没有出现在 javadoc 输出中。这对我来说似乎是另一个错误。 编辑： 错误在于注释位于 @Override 注释和方法声明的其余部分之间。文档注释必须位于之前整个方法声明，包括注释。所以注释 看起来 像一个文档注释，但是由于它在错误的地方，它被 javadoc 忽略了。

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

Java 8 中的 Java 文档不完整？

Incomplete Javadoc in Java 8?

java

javadoc

java-8