Java8中不完整的Javadoc？

Java8的Javadocs是否不完整

一些方法注释被省略，方法描述从基类复制（错误）（例如，带有注释“从类复制的描述：对象”）的方法

覆盖：

toString

类中的

Object

返回：

对象的字符串表示形式

实际的

toString

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

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

---

而不是从类对象继承的默认值，如图所示。

我想说您是正确的，这里有错误。这个toString（）方法记录在IntSummaryStatistics javadoc页面上。它没有在“从类对象派生的方法”中引用因此，我想说，如果此方法的行为与Object.toString（）不同，则应记录该行为。

我不同意将其称为“不正确”。但这是误导性的，尤其是关于类

对象如何实现
toString（）
的部分，因为实现实际上与此不同

我认为这一部分不应该被复制。它具有误导性，并且没有添加可利用的信息

但我完全同意这种形式的文档在某种程度上是“不正确的”，不适合这样的公共API。即使没有任何文档比这种文档更好。
是的，这里有两个不同的问题

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

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

这表示
对象定义并对所有子类施加要求的契约

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

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

getClass（）.getName（）+'@'+Integer.toHexString（hashCode（））

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

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

在JDK 8之前，没有办法将它们分开，所以文本要么是手工复制的（导致不一致），要么是使用
{@inheritDoc}
复制不需要的内容。在JDK 8中，一些新的javadoc标记，如
@implSpec
（实现规范）已引入将文档注释分隔为不同部分的标记。
{@inheritDoc}
指令可以选择性地继承这些部分，而不是继承整个文档。不幸的是，在本例中没有使用这些标记，因此我们需要做一些清理

新的标记在本文中有记录。注意，这些标记是JDK特有的，不能（目前）用于JDK之外的javadoc

缺少另一个部分。
对象.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
注释和方法声明的其余部分之间。文档注释必须位于整个方法声明之前，包括注释。因此注释看起来像文档注释，但是ce它在错误的地方，被javadoc忽略了

我已经提交并讨论了这些问题。
有人可能会争论这个问题。（复制的）文档说这个方法返回“一些字符串表示法”，并且只详细说明了对象类的字符串表示法（并不是说其他类可能没有返回其他字符串表示法）。在任何情况下，您都不应该依赖于任何特定的表示形式，因为这是一个以后可能会更改的实现细节。还有：“但是，使用Collector.toIntStatistics（）是安全的。”但它现在被称为
summaringit
。感谢您提出这个问题。它指出了JDK文档中的一些实际缺陷。接近投票人：这个观点是如何建立的？这个问题指出了一个有具体解决方案的实际问题。
IntSummaryStatistics{count=10, sum=129, min=2, average=12.900000, max=29}

@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() { ...