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 classObject
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 classObject
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.
You need to call mvn javadoc:fix to fix main Java source files (i.e. inside src/main/java directory) or mvn javadoc:test-fix to fix test Java source files (i.e. inside src/test/java directory).
In short, we use the @see tag when we want a link or a text entry that points to a reference. This tag adds a “See Also” heading to the reference. A document comment can hold any number of @see tags, all of which can be grouped under the same heading.
Accessing the Javadoc from NetbeansSelect the desired package, class or method name, right-click and select Show Javadoc. This will launch your default web browser and navigate to the Javadoc for the selected item.
Yes. If you don't have javadoc comments on a subclass, javadocs will be be generated based on the superclasses javadoc. If you define javadocs in the subclass they will replace the inherited javadocs, but you can use {@inheritDoc} to include the respective superclass javadoc comments in the subclass javadocs.
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 classObject
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.
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.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With