Incomplete Javadoc in Java 8?

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.

One could argue about that. The (copied) documentation says that this method returns "some string representation", and only details the string representation from the Object class (not saying that there may be no other string representation returned for other classes). In any case, you should probably **not** rely on any particular representation, because this is an implementation detail that may change later. — Marco13, May 14 '15 at 18:20
There's also : _"However, it is safe to use Collectors.toIntStatistics() "_ But it's now called `summarizingInt`. — Alexis C., May 14 '15 at 18:20
I agree that this should be fixed. Thank for pointing this out. +1 — Fabian Barney, May 14 '15 at 19:01
Thanks for asking this question. It pointed out some actual bugs in the JDK documentation. — Stuart Marks, May 15 '15 at 05:41
To close-voters: how is this opinion-based? The question pointed out an actual problem that has concrete solutions. — Stuart Marks, May 15 '15 at 05:43
Reminds me "The Dude" in the Big Lebowski: "That's just your OPINION, man." Doesn't make it so. There's a standard of what javadocs should say and this one is clearly at least partially wrong. @Stuart_Marks has opened bugs and the ultimate decision as to whether this is a matter of opinion will depend, at least partially, on the resolution of these bugs. — Steve Cohen, May 15 '15 at 18:37

Stuart Marks · Accepted Answer · 2015-05-15T05:40:30.653

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.

JDK-8080450 has been fixed in JDK 9. – Stuart Marks Jun 24 '15 at 23:12 — Stuart Marks, Jun 24 '15 at 23:12

score 4 · Answer 2 · answered May 14 '15 at 18:27

4

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.

answered May 14 '15 at 18:27

Steve Cohen

4,679
9
51
89

Thanks! Can this be reported to be corrected? – Jonathan May 14 '15 at 18:28
Report it and please report back what they say. I could be wrong, but this does not seem right to me. – Steve Cohen May 14 '15 at 18:30
I don't see where a javadoc documentation omission is reported -- only a java bug. Do you know? – Jonathan May 14 '15 at 18:32
It's probably irrelevant now since @Stuart_Marks has written the bugs but you CAN enter a BUG against documentation. The documentation is part of the JDK and it can have bugs. – Steve Cohen May 15 '15 at 18:47

Fabian Barney · Answer 3 · 2015-05-14T18:51:18.407

1

I disagree calling this "incorrect". But it is misleading especially the part about how the class Object implements toString(), because the implementation in fact differs from that.

This part should have not been copied in my opinion. It is misleading and does not add utilizable information.

But I totally agree that this form of documentation is somewhat "incorrect" and unworthy for such a public API. Even no documentation would have been better than this documentation.

edited May 14 '15 at 18:51

answered May 14 '15 at 18:32

Fabian Barney

14,219
5
40
60

What part is correct? It is all irrelevant! – Jonathan May 14 '15 at 18:34
@Jonathan Yes, it is irrelevant and misleading but correct. Class `Object` implements `toString()` the way described. – Fabian Barney May 14 '15 at 18:36
Documentation should document the method not state correct but irrelevant facts. By your measure, the docs might also say "Cows are herbivores" and be correct yet irrelevant. That, to me, is an incorrect form of documentation. – Jonathan May 14 '15 at 18:39
I totally agree calling the *form* of documentation in this case "incorrect". This starts with "copy & paste" which is evil ... – Fabian Barney May 14 '15 at 18:41
@Jonathan The entire first paragraph is correct and relevant. Only the second paragraph should not have been included. Mind you, it shouldn't be part of `Object.toString()`s javadoc either, it's a minor implementation detail. – biziclop May 14 '15 at 18:42
@biziclop The first paragraph is relevant only in class Object where it gives guidance to developers to override toString in a class specific manner. It is irrelevant in a class whose toString returns a comma separated list of the statistics. – Jonathan May 14 '15 at 18:45
@Jonathan And because it `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.` That's all you should know about it anyway. – biziclop May 14 '15 at 18:47

Incomplete Javadoc in Java 8?

3 Answers3