From 34a38f649a0ec0df5fd9634c4e2b15fef608c7a5 Mon Sep 17 00:00:00 2001
From: Jonathan Halterman <jhalterman@gmail.com>
Date: Fri, 27 Aug 2021 09:18:23 -0700
Subject: [PATCH] Improve javadocs wrt FailurePolicy exception handling
 conditions

---
 .../net/jodah/failsafe/FailurePolicy.java     | 13 ++++++++----
 .../java/net/jodah/failsafe/RetryPolicy.java  | 20 +++++++++++++------
 2 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/src/main/java/net/jodah/failsafe/FailurePolicy.java b/src/main/java/net/jodah/failsafe/FailurePolicy.java
index 04069503..2c166f65 100644
--- a/src/main/java/net/jodah/failsafe/FailurePolicy.java
+++ b/src/main/java/net/jodah/failsafe/FailurePolicy.java
@@ -26,10 +26,15 @@
 
 /**
  * A Policy that captures conditions to determine whether an execution is a failure.
- * <p>
- * By default, if no handlers are configured, the execution is considered a failure if an Exception was thrown. If
- * multuple handlers are configured, they are logically OR'ed.
- * </p>
+ * <ul>
+ *   <li>By default, any exception is considered a failure and will be handled by the policy. You can override this by
+ *   specifying your own {@code handle} conditions. The default exception handling condition will only be overridden by
+ *   another condition that handles failure exceptions such as {@link #handle(Class)} or {@link #handleIf(BiPredicate)}.
+ *   Specifying a condition that only handles results, such as {@link #handleResult(Object)} or
+ *   {@link #handleResultIf(Predicate)} will not replace the default exception handling condition.</li>
+ *   <li>If multiple {@code handle} conditions are specified, any condition that matches an execution result or failure
+ *   will trigger policy handling.</li>
+ * </ul>
  *
  * @param <S> self type
  * @param <R> result type
diff --git a/src/main/java/net/jodah/failsafe/RetryPolicy.java b/src/main/java/net/jodah/failsafe/RetryPolicy.java
index 3618c55d..812577e2 100644
--- a/src/main/java/net/jodah/failsafe/RetryPolicy.java
+++ b/src/main/java/net/jodah/failsafe/RetryPolicy.java
@@ -32,12 +32,20 @@
 
 /**
  * A policy that defines when retries should be performed.
- *
- * <p>
- * The {@code handle} methods describe when a retry should be performed for a particular failure. The {@code
- * handleResult} methods describe when a retry should be performed for a particular result. If multiple {@code handle}
- * or {@code handleResult} conditions are specified, any matching condition can allow a retry. The {@code abortOn},
- * {@code abortWhen} and {@code abortIf} methods describe when retries should be aborted.
+ * <ul>
+ *   <li>By default, a RetryPolicy will retry up to {@code 2} times when any {@code Exception} is thrown, with no delay
+ *   between retry attempts.</li>
+ *   <li>You can change the default number of retry attempts and delay between retries by using the {@code with}
+ *   configuration methods.</li>
+ *   <li>You can change the default {@code Exception} handling behavior by specifying
+ *   your own {@code handle} conditions. The default exception handling condition will only be overridden by
+ *   another condition that handles failure exceptions such as {@link #handle(Class)} or {@link #handleIf(BiPredicate)}.
+ *   Specifying a condition that only handles results, such as {@link #handleResult(Object)} or
+ *   {@link #handleResultIf(Predicate)} will not replace the default exception handling condition.</li>
+ *   <li>If multiple {@code handle} conditions are specified, any condition that matches an execution result or failure
+ *   can cause a retry.</li>
+ *   <li>The {@code abortOn}, {@code abortWhen} and {@code abortIf} methods describe when retries should be aborted.</li>
+ * </ul>
  * <p>
  * Note: RetryPolicy extends {@link DelayablePolicy} and {@link FailurePolicy} which offer additional configuration.
  * </p>