docs(datastore): add comments explaining exception unwrapping and interruption handling

Author: lqiu96

java-datastore/datastore-v1-proto-client/src/test/java/com/google/datastore/v1/client/it/ITDatastoreProtoClientTest.java

@@ -139,6 +139,9 @@ private static <V> V runWithRetry(
       return submittedFuture.get();
     } catch (ExecutionException e) {
       Throwable cause = e.getCause();
+      // submittedFuture.get() wraps any exception thrown during execution in an ExecutionException.
+      // We unwrap and rethrow the actual cause (Exception or Error) directly so that test failures
+      // report the root cause (e.g., DatastoreException or AssertionError) instead of the wrapper.
       if (cause instanceof Exception) {
         throw (Exception) cause;
       }
@@ -147,6 +150,7 @@ private static <V> V runWithRetry(
       }
       throw e;
     } catch (InterruptedException e) {
+      // Restore the interrupted status before rethrowing, as per Java concurrency best practices.
       Thread.currentThread().interrupt();
       throw e;
     }

java-datastore/google-cloud-datastore-utils/src/test/java/com/google/datastore/utils/it/ITDatastoreProtoClientTest.java

@@ -135,6 +135,9 @@ private static <V> V runWithRetry(
       return submittedFuture.get();
     } catch (ExecutionException e) {
       Throwable cause = e.getCause();
+      // submittedFuture.get() wraps any exception thrown during execution in an ExecutionException.
+      // We unwrap and rethrow the actual cause (Exception or Error) directly so that test failures
+      // report the root cause (e.g., DatastoreException or AssertionError) instead of the wrapper.
       if (cause instanceof Exception) {
         throw (Exception) cause;
       }
@@ -143,6 +146,7 @@ private static <V> V runWithRetry(
       }
       throw e;
     } catch (InterruptedException e) {
+      // Restore the interrupted status before rethrowing, as per Java concurrency best practices.
       Thread.currentThread().interrupt();
       throw e;
     }