Incomplete Javadoc in Java 8? [closed]

Question

Is the Javadocs for Java 8 incomplete?

Some of the method comments are omitted and the method description is copied (incorrectly) from a base class (e.g. the java.util.IntSummaryStatistics toString() method with the note "Description copied from class: Object".

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.

The actual toString method returns class specific information like this:

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

and not the default inherited from class Object, as shown here.

Answer 1

Yes, there are a couple different problems here.

The IntSummaryStatistics.toString specification has some text copied from Object.toString, which it overrides. The first part is correct:

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.

This represents the contract that Object.toString defines and that imposes requirements on all subclasses.

The second part of the specification copied from Object.toString is this:

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())

This is correct, but irrelevant, since it talks about implementation of Object.toString in the specification of IntSummaryStatistics.toString. It's inappropriate for this to have been copied here. Note that this is talking about the implementation of Object.toString and not about the contract that overrides are required to implement.

The problem is that the javadoc {@inheritDoc} directive, which is used in the doc comment for IntSummaryStatistics.toString, copies the whole thing, when it's really only necessary to copy part of it. Specifically, the contract imposed on subclasses should be copied, but the implementation specification should not be.

Until JDK 8 there was no way to separate these, so text was either copied by hand (leading to it becoming inconsistent) or {@inheritDoc} was used, which copies unwanted stuff. In JDK 8, some new javadoc tags such as @implSpec (implementation specification) have been introduced that separate a doc comment into different sections. The {@inheritDoc} directive can selectively inherit these sections instead of inheriting the entirety of the documentation. Unfortunately, those tags weren't used in this case, so we have some cleaning up to do.

The new tags are documented in this informational JEP. Note that these tags are JDK-specific and can't (yet) be used for javadoc outside the JDK.

There's another piece missing. The Object.toString doc comment is conceptually divided into a portion defining the contract on subclasses and a portion defining its implementation. Ideally we'd like the contract portion copied into the IntSummaryStatistics.toString documentation and for there to be another section that defines the implementation of IntSummaryStatistics.toString. It turns out there is, but it's not visible! The source code for IntSummaryStatistics.toString has this as its doc comment:

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

Unfortunately the text "Returns a non-empty string representation..." doesn't appear in the javadoc output. That seems like another bug to me. EDIT: the bug is that the comment is between the @Override annotation and the rest of the method declaration. The doc comment must come before the entire method declaration, including annotations. So the comment looks like a doc comment, but since it's in the wrong place, it's ignored by javadoc.

I've filed JDK-8080449 and JDK-8080450 to cover these issues.

Answer 2

I would say that you are correct that there is something wrong here. This toString() method is documented on the IntSummaryStatistics javadoc page. It is not referenced in a "Methods derived from class Object" link. So I would say that if this method has a different behavior than Object.toString() that behavior should be documented.