Improve docs around policy listeners

Per issue #248

Author: jhalterman

src/main/java/net/jodah/failsafe/PolicyListeners.java

@@ -33,15 +33,18 @@ public class PolicyListeners<S, R> {
   EventListener successListener;
 
   /**
-   * Registers the {@code listener} to be called when an execution fails for a {@link Policy}.
+   * Registers the {@code listener} to be called when a {@link Policy} fails to handle an execution. This means that not
+   * only was the supplied execution considered a failure by the policy, but that the policy was unable to produce a
+   * successful result.
    */
   public S onFailure(CheckedConsumer<? extends ExecutionCompletedEvent<R>> listener) {
     failureListener = EventListener.of(Assert.notNull(listener, "listener"));
     return (S) this;
   }
 
   /**
-   * Registers the {@code listener} to be called when an execution is successful for a {@link Policy}.
+   * Registers the {@code listener} to be called when a {@link Policy} succeeds in handling an execution. This means
+   * that the supplied execution either succeeded, or if it failed, the policy was able to produce a successful result.
    */
   public S onSuccess(CheckedConsumer<? extends ExecutionCompletedEvent<R>> listener) {
     successListener = EventListener.of(Assert.notNull(listener, "listener"));