On Mon, 10 Nov 2025 15:31:31 GMT, Viktor Klang <[email protected]> wrote:
>> This is docs only change to a new section to the Thread class description on
>> Thread Interruption. The new section provides guidance on handling
>> InterruptedException. A subset of that guidance is also proposed for the
>> InterruptedException class description.
>
> src/java.base/share/classes/java/lang/Thread.java line 157:
>
>> 155: * }
>> 156: *
>> 157: * <h2><a id="inheritance">Inheritance When Creating Threads</a></h2>
>
> Detected an inconsistency: Capital "W" on When but not capital "A" on "and"
> in the previous heading
These headings are in in title case so "When" is capitalised but not "and".
> src/java.base/share/classes/java/lang/Thread.java line 185:
>
>> 183: * <p> If a thread executing {@link #sleep(long) Thread.sleep} or
>> {@link Object#wait()
>> 184: * Object.wait} is interrupted then it causes the method to return
>> early and throw
>> 185: * {@link InterruptedException}. Methods that throw {@code
>> InterruptedException} do so after
>
> I think something like this is clearer:
>
> Suggestion:
>
> * Object.wait} is interrupted then it causes the method to exit early by
> throwing an
> * {@link InterruptedException}. Methods that throw {@code
> InterruptedException} do so after
The previous paragraph establishes the phrase "return early" so this is why it
is re-used here maybe "method to exit" would be better here, I'll play with it.
> src/java.base/share/classes/java/lang/Thread.java line 189:
>
>> 187: * should rethrow the exception, or restore the current thread's
>> interrupted status, with
>> 188: * {@link #currentThread() Thread.currentThread()}.{@link
>> #interrupt()}, before continuing
>> 189: * normally or handling it by throwing another type of exception.
>
> Perhaps add "even if wrapping the InterruptedException"?
I've added a sentence for this.
> src/java.base/share/classes/java/lang/Thread.java line 205:
>
>> 203: * {@code Thread} also defines the static {@link #interrupted()
>> Thread.interrupted()}
>> 204: * method to test the current thread's interrupted status and clear it.
>> It should be rare
>> 205: * to need to use this method.
>
> I wonder if we can give clearer instructions/examples as to when to use this
> method?
That's good idea, I've put a first version in interrupted() as an apiNote.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2511850457
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2511858145
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2511859774
PR Review Comment: https://git.openjdk.org/jdk/pull/28216#discussion_r2511852468
