Java 8中不完整的Javadoc？

Question

Java 8的Javadocs是不完整的？

省略了一些方法注释,并且从基类(例如java.util.IntSummaryStatistics toString()方法复制(错误地)方法描述,并注释"从类:对象复制的描述".

public String toString()

从类复制的描述: Object

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

toString类的方法Object返回一个字符串,该字符串由对象为实例的类的名称,符号字符"@"和对象的哈希码的无符号十六进制表示组成.换句话说,此方法返回一个等于值的字符串:

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

覆盖:

toString 在班上 Object

返回:

对象的字符串表示形式.

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

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

而不是默认的继承自Object类,如图所示这里.

Answer 1

是的,这里有几个不同的问题.

该IntSummaryStatistics.toString规范有一些文字从复制Object.toString,它覆盖.第一部分是正确的:

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

这表示合同是Object.toString定义并规定所有子类的要求.

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

toString类的方法Object返回一个字符串,该字符串由对象为实例的类的名称,符号字符"@"和对象的哈希码的无符号十六进制表示组成.换句话说,此方法返回一个等于值的字符串:

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

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

问题是,{@inheritDoc}在doc注释中使用的javadoc 指令会IntSummaryStatistics.toString复制整个事物,而实际上只需要复制它的一部分.具体而言,应复制对子类施加的合同,但不应实施实施规范.

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

新信息记录在此信息JEP中.请注意,这些标记是JDK特定的,不能(还)用于JDK之外的javadoc.

还有另一件失踪.的Object.toString文档注释在概念上被分割成限定于子类,并限定其实现的一部分的合同的部分.理想情况下,我们希望将合同部分复制到IntSummaryStatistics.toString文档中,并为另一部分定义实现IntSummaryStatistics.toString.原来有,但它不可见!源代码IntSummaryStatistics.toString将此作为其doc评论:

@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来解决这些问题.