Summary

Clarify java.util.concurrent.StructuredTaskScope::join to make it clear that InterruptedException is thrown if the join method is invoked with the current thread's interrupted status set.

Problem

StructuredTaskScope::join throws InterruptedException if the current thread is interrupted before or while waiting. The current thread's interrupted status is cleared when this exception is thrown. This isn't clear from the current docs.

Solution

Update the @throws text to make it clear that InterruptedException is thrown if the current thread is interrupted before or while waiting. Also make it clear that the interrupted status is cleared when this exception is thrown.

Specification

@@ -1081,10 +1081,9 @@ static <T> StructuredTaskScope<T, Void> open() {
      * does not throw then the {@code Joiner}'s {@code result()} method is invoked to
      * get the result or throw.
      *
-     * <p> This method may only be invoked by the scope owner. Once the result or
-     * exception outcome is obtained, this method may not be invoked again. The only
-     * case where the method may be called again is where {@code InterruptedException}
-     * is thrown while waiting.
+     * <p> This method may only be invoked by the scope owner. It may only be invoked once
+     * to get the result, exception or timeout outcome, unless the previous invocation
+     * resulted in an {@code InterruptedException} being thrown.
      *
      * @return the result
      * @throws WrongThreadException if the current thread is not the scope owner
@@ -1093,8 +1092,11 @@ static <T> StructuredTaskScope<T, Void> open() {
      * exception from {@link Joiner#result() Joiner.result()} as the cause
      * @throws TimeoutException if a timeout is set, the timeout expires before or while
      * waiting, and {@link Joiner#onTimeout() Joiner.onTimeout()} throws this exception
-     * @throws InterruptedException if interrupted while waiting
+     * @throws InterruptedException if the current thread is interrupted before or
+     * while waiting. The current thread's interrupted status is cleared when this
+     * exception is thrown.
      * @since 25
+     * @see Thread##thread-interruption Thread Interruption
      */
     R join() throws InterruptedException;