RFR(s) #2: 6344935: (spec) clarify specifications for Object.wait overloads

[David Holmes]

Hi Stuart,

You're a brave man :) I shall refrain from mentioning any of the 
existing wording quirks that really irritate me. :)

On 19/08/2017 5:59 AM, Stuart Marks wrote:
> Hi all,
> 
> Well nothing is ever simple, is it? Prompted by David Holmes' comments, 
> I looked at the other overloads of wait(), and I agree that they're in 
> need of cleanup. I decided to put the most complete version of the 
> specification into the wait(timeout, nanos) overload, and then I simply 
> redefined the other overloads wait(timeout) and wait() in terms of the 
> first. This avoids redundancies that creep in when what ought to be the 
> same specification is replicated across different overloads (which is 
> probably how the specs for these methods diverged in the first place).
> 
> I've incorporated comments from Martin Buchholz and Hans Boehm. I've 
> done a little bit of rewriting where I thought it was necessary, 
> particularly in the lead sentences of the specs. Plus I added a few 
> editorial cleanups.
> 
> Since this has gotten bigger, here's a webrev:
> 
> http://cr.openjdk.java.net/~smarks/reviews/6344935/webrev.1/

Overall looks good. Only nit I have is that for the:

  * @throws InterruptedException if any thread interrupted the current 
thread before or
  *         while the current thread was waiting

I prefer to see the:

"The <i>interrupted status</i> of the current thread is cleared when 
this exception is thrown."

remain on the @throws. I just think people are more likely to look at 
the @throws than read all the main javadoc.

Thanks,
David

> Please review. Thanks.
> 
> s'marks
>