Document semantics of RetryException regarding cause and suppressed exceptions

Closes gh-35337

Author: sbrannen

spring-core/src/main/java/org/springframework/core/retry/RetryException.java

@@ -22,6 +22,11 @@
 /**
  * Exception thrown when a {@link RetryPolicy} has been exhausted.
  *
+ * <p>A {@code RetryException} will contain the last exception thrown by the
+ * {@link Retryable} operation as the {@linkplain #getCause() cause} and any
+ * exceptions from previous attempts as {@linkplain #getSuppressed() suppressed
+ * exceptions}.
+ *
  * @author Mahmoud Ben Hassine
  * @since 7.0
  * @see RetryOperations

spring-core/src/main/java/org/springframework/core/retry/RetryOperations.java

@@ -34,15 +34,17 @@
 public interface RetryOperations {
 
 	/**
-	 * Execute the given {@link Retryable} (according to the {@link RetryPolicy}
-	 * configured at the implementation level) until it succeeds, or eventually
-	 * throw an exception if the {@code RetryPolicy} is exhausted.
+	 * Execute the given {@link Retryable} operation according to the {@link RetryPolicy}
+	 * configured at the implementation level.
+	 * <p>If the {@code Retryable} succeeds, its result will be returned. Otherwise, a
+	 * {@link RetryException} will be thrown to the caller. The {@code RetryException}
+	 * will contain the last exception thrown by the {@code Retryable} operation as the
+	 * {@linkplain RetryException#getCause() cause} and any exceptions from previous
+	 * attempts as {@linkplain RetryException#getSuppressed() suppressed exceptions}.
 	 * @param retryable the {@code Retryable} to execute and retry if needed
 	 * @param <R> the type of the result
 	 * @return the result of the {@code Retryable}, if any
-	 * @throws RetryException if the {@code RetryPolicy} is exhausted; exceptions
-	 * encountered during retry attempts should be made available as suppressed
-	 * exceptions
+	 * @throws RetryException if the {@code RetryPolicy} is exhausted
 	 */
 	<R> @Nullable R execute(Retryable<? extends @Nullable R> retryable) throws RetryException;
 

spring-core/src/main/java/org/springframework/core/retry/RetryTemplate.java

@@ -104,15 +104,17 @@ public void setRetryListener(RetryListener retryListener) {
 
 
 	/**
-	 * Execute the supplied {@link Retryable} according to the configured retry
-	 * and backoff policies.
-	 * <p>If the {@code Retryable} succeeds, its result will be returned. Otherwise,
-	 * a {@link RetryException} will be thrown to the caller.
+	 * Execute the supplied {@link Retryable} operation according to the configured
+	 * {@link RetryPolicy}.
+	 * <p>If the {@code Retryable} succeeds, its result will be returned. Otherwise, a
+	 * {@link RetryException} will be thrown to the caller. The {@code RetryException}
+	 * will contain the last exception thrown by the {@code Retryable} operation as the
+	 * {@linkplain RetryException#getCause() cause} and any exceptions from previous
+	 * attempts as {@linkplain RetryException#getSuppressed() suppressed exceptions}.
 	 * @param retryable the {@code Retryable} to execute and retry if needed
 	 * @param <R> the type of the result
 	 * @return the result of the {@code Retryable}, if any
-	 * @throws RetryException if the {@code RetryPolicy} is exhausted; exceptions
-	 * encountered during retry attempts are available as suppressed exceptions
+	 * @throws RetryException if the {@code RetryPolicy} is exhausted
 	 */
 	@Override
 	public <R> @Nullable R execute(Retryable<? extends @Nullable R> retryable) throws RetryException {