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.


Comments

Post a Comment

Popular posts from this blog

c++ - Difference between pre and post decrement in recursive function argument -

i have following sample code used pre-decrement void function(int c) { if(c == 0) { return; } else { cout << "dp" << c << endl; function(--c); cout << c << endl; return; } } this function give output input 4 : dp3 dp2 dp1 dp0 0 1 2 3 but when use post decrement void function(int c) { if(c == 0) { return; } else { cout << "dp" << c << endl; function(c--); cout << c << endl; return; } } output goes in infinite loop dp4 can explain me in detail why happens ? this happens because function(c--) called same value of c , when finishes c decremented. recursively called, hence called same value no chance of return , hit stack overflow error. assume this, int x = 1, y = 0; y = x++ result y == 1 , x == 2. if y = ++x , bot x , y 2.
Read more

php - Nothing but 'run(); ' when browsing to my local project, how do I fix this? -

i added new project. made mistake in projectname.conf file in sites-available apache2, led me reinstalling apache2. after reinstalling , re-enabling projects on every page of every project .. <body> run(); </body> .. i've run composer update, restarted service, restarted pc, checked config files, tried disabling new project. there nothing in error log, , access.log: 127.0.0.1 - - [15/may/2015:01:40:47 +0200] "get / http/1.1" 304 181 "-" "mozilla/5.0 (x11; ubuntu; linux x86_64; rv:38.0) gecko/20100101 firefox/38.0" maybe i'm forgetting apache2 reinstall? don't think did different last time installed it. looks haven't setup php correctly. take @ this great guide , maybe you're forgetting link php config apache2.
Read more

php - How can I echo out this array? -

i don't know how go grabbing data in variable , put foreach loop. class tree{ private $info = array( array('name'=>'jim','state'=>'nu','company'=>'nu','phone'=>array('cell'=>'5615111111','office'=>'5611111111'),'email'=>array('primary'=>'exs@example.com','ex@there.com')), array('name'=>'joe smith','city'=>'phoenix','phone'=>'4805551111','email'=>'jsmith@some_email.com'), array('name'=>'john doe','city'=>'chandler','company'=>'doe co.','email'=>array('jdoe@gmail.com','personal'=>'email@email.com'),'phone'=>'6025550002') ); } if you're inside of class, can access private variable using $this->variablename . example, i...
Read more