Bug ID: JDK-8080450 doc for Double/Int/LongSummaryStatistics.toString has errors

Versions (Unresolved/Resolved/Fixed)

The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.

JDK 9
9 b71Fixed

The specification for IntSummaryStatistics.toString is entirely copied from Object.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())
==========

This copies the contract portion of Object.toString's spec, but it shouldn't copy the implementation portion of the specification. Thus, use of @implSpec combined with {@inheritDoc} is called for here. (See JDK-8080449 regarding Object.toString and JDK-8068562 regarding the @implSpec tag.)

In addition, the source code for IntSummaryStatistics.toString has this as its doc comment:

    /**
     * {@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.
     */

For some reason the text "Returns a non-empty string representation..." doesn't appear in the javadoc output. This may be a javadoc bug.

This is probably just one instance of a general problem where overriding methods' specifications should be cleaned up to inherit selectively from their superclass.

Seen on StackOverflow: http://stackoverflow.com/q/30244464/1441122

Here's a little detector for when an annotation appears before a javadoc comment: awk ' BEGIN { atprev = 0; } atprev > 0 && /\/\\/ { print FILENAME, FNR } { atprev = match($0, /^ *@/) } ' "$@" There are a handful of places where this occurs in the JDK repo, but the SummaryStatistics classes are the only places where it affects public javadoc output. Others are doc comments on private methods, in tests, or in example classes.
24-06-2015
LongSummaryStatistics also has @Override in the wrong place. DoubleSummaryStatistics has it in the right place. However, all three summary statistics classes unnecessarily have {@inheritDoc}, which brings in the extraneous and confusing doc from Object. I'll fix these up too.
24-06-2015
It's not strictly a bug that javadoc ignores this comment. The javadoc tool page [1] says ("Placement of Comments"): �� Documentation comments are recognized only when placed immediately before class, interface, constructor, method, or field declarations. Documentation comments placed in the body of a method are ignored. �� Note that, syntactically, annotations are modifiers. One could do this: public @Override String toString() { ... } although I suppose it would be perverse to do so. Since modifiers are part of a method declaration, a comment placed among the modifiers would not be considered a doc comment. Thus: /** doc comment / public @Deprecated static /* ignored comment */ void foo() { } It would be nice if there were a warning for this; it seems like an easy mistake to make. [1] http://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html
15-05-2015
Is this a JavaDoc bug?
15-05-2015
Ah, here's the problem. The complete declaration of IntSummaryStatistics.toString is as follows: @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() { ... } The javadoc comment must occur before* any annotations on the item being documented. When the doc comment appears between @Override and the rest of the method declaration, it's apparently ignored entirely!
14-05-2015