Improve javadocs wrt FailurePolicy exception handling conditions

Author: jhalterman

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

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>