Incomplete Javadoc in Java 8? -

is javadocs java 8 incomplete?

some of method comments omitted , method description copied (incorrectly) base class (e.g. java.util.intsummarystatistics tostring() method note "description copied class: object".

public string tostring()

description copied class: object

returns string representation of object. in general, tostring method returns string "textually represents" object. result should concise informative representation easy person read. recommended subclasses override method.

the tostring method class object returns string consisting of name of class of object instance, at-sign character '@', , unsigned hexadecimal representation of hash code of object. in other words, method returns string equal value of:

getclass().getname() + '@' + integer.tohexstring(hashcode())

overrides:

tostring in class object

returns:

a string representation of object.

the actual tostring method returns class specific information this:

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

and not default inherited class object, shown here.

yes, there couple different problems here.

the intsummarystatistics.tostring specification has text copied object.tostring, overrides. first part correct:

returns string representation of object. in general, tostring method returns string "textually represents" object. result should concise informative representation easy person read. recommended subclasses override method.

this represents contract object.tostring defines , imposes requirements on subclasses.

the second part of specification copied object.tostring this:

the tostring method class object returns string consisting of name of class of object instance, at-sign character '@', , unsigned hexadecimal representation of hash code of object. in other words, method returns string equal value of:

getclass().getname() + '@' + integer.tohexstring(hashcode())

this correct, irrelevant, since talks implementation of object.tostring in specification of intsummarystatistics.tostring. it's inappropriate have been copied here. note talking implementation of object.tostring , not contract overrides required implement.

the problem javadoc {@inheritdoc} directive, used in doc comment intsummarystatistics.tostring, copies whole thing, when it's necessary copy part of it. specifically, contract imposed on subclasses should copied, implementation specification should not be.

until jdk 8 there no way separate these, text either copied hand (leading becoming inconsistent) or {@inheritdoc} used, copies unwanted stuff. in jdk 8, new javadoc tags such @implspec (implementation specification) have been introduced separate doc comment different sections. {@inheritdoc} directive can selectively inherit these sections instead of inheriting entirety of documentation. unfortunately, tags weren't used in case, have cleaning do.

the new tags documented in informational jep. note these tags jdk-specific , can't (yet) used javadoc outside jdk.

there's piece missing. object.tostring doc comment conceptually divided portion defining contract on subclasses , portion defining implementation. ideally we'd contract portion copied intsummarystatistics.tostring documentation , there section defines implementation of intsummarystatistics.tostring. turns out there is, it's not visible! source code intsummarystatistics.tostring has doc comment:

@override /**  * {@inheritdoc}  *  * returns non-empty string representation of object suitable  * debugging. exact presentation format unspecified , may vary  * between implementations , versions.  */ public string tostring() { ... 

unfortunately text "returns non-empty string representation..." doesn't appear in javadoc output. seems bug me. edit: bug comment between @override annotation , rest of method declaration. doc comment must come before entire method declaration, including annotations. comment looks doc comment, since it's in wrong place, it's ignored javadoc.

i've filed jdk-8080449 , jdk-8080450 cover these issues.