From 5eb03a7eb127826e89f1e378c977627b4db1b0ad Mon Sep 17 00:00:00 2001 From: Scott Leberknight <174812+sleberknight@users.noreply.github.com> Date: Sun, 1 Sep 2024 13:11:58 -0400 Subject: [PATCH] Fix/cleanup grammar in some documentation --- README.md | 10 +++++----- src/main/java/org/kiwiproject/retry/Attempt.java | 4 ++-- .../java/org/kiwiproject/retry/RetryException.java | 2 +- .../java/org/kiwiproject/retry/RetryListener.java | 2 +- src/main/java/org/kiwiproject/retry/Retryer.java | 8 ++++---- .../java/org/kiwiproject/retry/RetryerBuilder.java | 12 ++++++------ .../java/org/kiwiproject/retry/StopStrategies.java | 2 +- .../java/org/kiwiproject/retry/WaitStrategy.java | 2 +- 8 files changed, 21 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index cc74b1a..9bdb263 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ public int readAnInteger() throws IOException { ``` The following creates a `Retryer` that will retry if the result of the method is zero, if an `IOException` is -thrown, or if any other `RuntimeException` is thrown from the `call()` method. It will stop after 3 unsuccessful +thrown, or if any other `RuntimeException` is thrown from the `call()` method. It will stop after three unsuccessful attempts and throw a `RetryException` that contains information about the last failed attempt. If an `Exception` is thrown by the `call()` method, it can be retrieved from the `RetryException`. @@ -98,7 +98,7 @@ the result or exception, and the time since the first attempt was made by a `Ret ## Exponential Backoff Create a `Retryer` that retries forever, waiting after every failed retry in increasing exponential backoff -intervals until at most 5 minutes. After 5 minutes, retry from then on in 5 minute intervals. +intervals until at most 5 minutes. After 5 minutes, retry from then on in 5-minute intervals. ```java var retryer = RetryerBuilder.newBuilder() @@ -115,7 +115,7 @@ role it played in the development of TCP/IP in [Congestion Avoidance and Control ## Fibonacci Backoff Create a `Retryer` that retries forever, waiting after every failed retry in increasing Fibonacci backoff -intervals until at most 2 minutes. After 2 minutes, retry from then on in 2 minute intervals. +intervals until at most 2 minutes. After 2 minutes, retry from then on in 2-minute intervals. ```java var retryer = RetryerBuilder.newBuilder() @@ -129,11 +129,11 @@ var retryer = RetryerBuilder.newBuilder() Similar to the `ExponentialWaitStrategy`, the `FibonacciWaitStrategy` follows a pattern of waiting an increasing amount of time after each failed attempt. -Instead of an exponential function it's (obviously) using a [Fibonacci sequence](https://en.wikipedia.org/wiki/Fibonacci_numbers) +Instead of an exponential function, it's (obviously) using a [Fibonacci sequence](https://en.wikipedia.org/wiki/Fibonacci_numbers) to calculate the wait time. Depending on the problem at hand, the `FibonacciWaitStrategy` might perform better and lead to better throughput -than the `ExponentialWaitStrategy` - at least according to +than the `ExponentialWaitStrategy` - at least, according to [A Performance Comparison of Different Backoff Algorithms under Different Rebroadcast Probabilities for MANETs](https://www.researchgate.net/publication/255672213_A_Performance_Comparison_of_Different_Backoff_Algorithms_under_Different_Rebroadcast_Probabilities_for_MANET%27s). The implementation of `FibonacciWaitStrategy` is using an iterative version of the Fibonacci because a (naive) recursive diff --git a/src/main/java/org/kiwiproject/retry/Attempt.java b/src/main/java/org/kiwiproject/retry/Attempt.java index 129c7a2..22a40e5 100644 --- a/src/main/java/org/kiwiproject/retry/Attempt.java +++ b/src/main/java/org/kiwiproject/retry/Attempt.java @@ -43,7 +43,7 @@ private Attempt(T result, Exception exception, int attemptNumber, long delaySinc /** * Create a new {@link Attempt} that has a result. * - * @param result the result of the attempt, may be null + * @param result the result of the attempt; it may be null * @param attemptNumber the number of this attempt * @param delaySinceFirstAttempt the delay in milliseconds since the first attempt was made * @param the type of result @@ -74,7 +74,7 @@ static Attempt newExceptionAttempt(Exception exception, int attemptNumber */ public boolean hasResult() { // Check the exception field, because the Callable may have succeeded and returned null. - // In that case both exception and result will be null. + // In that case, both exception and result will be null. return exception == null; } diff --git a/src/main/java/org/kiwiproject/retry/RetryException.java b/src/main/java/org/kiwiproject/retry/RetryException.java index 0816e69..0c99175 100644 --- a/src/main/java/org/kiwiproject/retry/RetryException.java +++ b/src/main/java/org/kiwiproject/retry/RetryException.java @@ -83,7 +83,7 @@ public Attempt getLastFailedAttempt() { * @param resultType the type of result which the Attempt must contain * @param the generic type of the Attempt * @return the last failed attempt - * @throws IllegalStateException if the Attempt has a result that is not an instance of {@code resultType} + * @throws IllegalStateException if the Attempt has a result which is not an instance of {@code resultType} * @apiNote The type {@code T} of the {@code Attempt} must be explicitly specified * because the Java Language Specification does not permit generic subclasses of Throwable. * See the API Note in {@link #getLastFailedAttempt()} for more details. diff --git a/src/main/java/org/kiwiproject/retry/RetryListener.java b/src/main/java/org/kiwiproject/retry/RetryListener.java index e73fc9b..bbfeaf9 100644 --- a/src/main/java/org/kiwiproject/retry/RetryListener.java +++ b/src/main/java/org/kiwiproject/retry/RetryListener.java @@ -11,7 +11,7 @@ public interface RetryListener { * retry predicate and stop strategies are applied. * * @param attempt the current {@link Attempt} - * @apiNote No exceptions should be thrown from this method. But, if an exception is thrown by an + * @apiNote No exceptions should be thrown from this method. But if an exception is thrown by an * implementation, it will be silently ignored so that it does not halt processing of a {@link Retryer}. */ void onRetry(Attempt attempt); diff --git a/src/main/java/org/kiwiproject/retry/Retryer.java b/src/main/java/org/kiwiproject/retry/Retryer.java index d52d0d5..a74dacf 100644 --- a/src/main/java/org/kiwiproject/retry/Retryer.java +++ b/src/main/java/org/kiwiproject/retry/Retryer.java @@ -36,7 +36,7 @@ public final class Retryer { * @param stopStrategy the strategy used to decide when the retryer must stop retrying * @param waitStrategy the strategy used to decide how much time to sleep between attempts * @param blockStrategy the strategy used to decide how to block between retry attempts; - * eg, Thread#sleep(), latches, etc. + * e.g., Thread#sleep(), latches, etc. * @param retryPredicates the predicates used to decide if the attempt must be retried (without * regard to the StopStrategy). * @param listeners collection of retry listeners @@ -66,7 +66,7 @@ public final class Retryer { /** * Executes the given callable, retrying if necessary. If the retry predicate * accepts the attempt, the stop strategy is used to decide if a new attempt - * must be made. Then the wait strategy is used to decide how much time to sleep + * must be made. Then the wait strategy is used to decide how much time to sleep, * and a new attempt is made. * * @param callable the callable task to be executed @@ -124,7 +124,7 @@ private static void safeInvokeListener(RetryListener listener, Attempt at /** * Executes the given runnable, retrying if necessary. If the retry predicate * accepts the attempt, the stop strategy is used to decide if a new attempt - * must be made. Then the wait strategy is used to decide how much time to sleep + * must be made. Then the wait strategy is used to decide how much time to sleep, * and a new attempt is made. * * @param runnable the runnable task to be executed @@ -157,7 +157,7 @@ private T getOrThrow(Attempt attempt) throws RetryException { } /** - * Applies the retry predicates to the attempt, in order, until either one + * Applies the retry predicates to the attempt, in order, until any * predicate returns true or all predicates return false. * * @param attempt The attempt made by invoking the call diff --git a/src/main/java/org/kiwiproject/retry/RetryerBuilder.java b/src/main/java/org/kiwiproject/retry/RetryerBuilder.java index f764695..cb4bb0e 100644 --- a/src/main/java/org/kiwiproject/retry/RetryerBuilder.java +++ b/src/main/java/org/kiwiproject/retry/RetryerBuilder.java @@ -55,7 +55,7 @@ public RetryerBuilder withWaitStrategy(@NonNull WaitStrategy waitStrategy) { /** * Sets the stop strategy used to decide when to stop retrying. The default strategy - * is to not stop at all . + * is to not stop at all. * * @param stopStrategy the strategy used to decide when to stop retrying * @return this @@ -97,7 +97,7 @@ public RetryerBuilder withAttemptTimeLimiter(@NonNull AttemptTimeLimiter attempt } /** - * Configures the retryer to retry if an exception (i.e. any Exception or subclass + * Configures the retryer to retry if an exception (i.e., any Exception or subclass * of Exception) is thrown by the call. * * @return this @@ -108,7 +108,7 @@ public RetryerBuilder retryIfException() { } /** - * Configures the retryer to retry if a runtime exception (i.e. any RuntimeException or subclass + * Configures the retryer to retry if a runtime exception (i.e., any RuntimeException or subclass * of RuntimeException) is thrown by the call. * * @return this @@ -119,7 +119,7 @@ public RetryerBuilder retryIfRuntimeException() { } /** - * Configures the retryer to retry if an exception is thrown by the call and the thrown exception's type + * Configures the retryer to retry if the call throws an exception, and the thrown exception's type * is the given class (or a subclass of the given class). * * @param exceptionClass the type of the exception which should cause the retryer to retry @@ -132,8 +132,8 @@ public RetryerBuilder retryIfExceptionOfType(@NonNull Class } /** - * Configures the retryer to retry if an exception satisfying the given predicate is - * thrown by the call. + * Configures the retryer to retry if the call + * throws an exception satisfying the given predicate. * * @param exceptionPredicate the predicate which causes a retry if satisfied * @return this diff --git a/src/main/java/org/kiwiproject/retry/StopStrategies.java b/src/main/java/org/kiwiproject/retry/StopStrategies.java index 98e167a..b1e90ed 100644 --- a/src/main/java/org/kiwiproject/retry/StopStrategies.java +++ b/src/main/java/org/kiwiproject/retry/StopStrategies.java @@ -43,7 +43,7 @@ public static StopStrategy stopAfterAttempt(int attemptNumber) { * given delay amount. If it has exceeded this delay, then using this * strategy causes the retrying to stop. * - * @param duration the delay, starting from first attempt + * @param duration the delay, starting from the first attempt * @param timeUnit the unit of the duration * @return a stop strategy which stops after {@code duration} time in the given {@code timeUnit} */ diff --git a/src/main/java/org/kiwiproject/retry/WaitStrategy.java b/src/main/java/org/kiwiproject/retry/WaitStrategy.java index fd9dbfd..85867bc 100644 --- a/src/main/java/org/kiwiproject/retry/WaitStrategy.java +++ b/src/main/java/org/kiwiproject/retry/WaitStrategy.java @@ -9,7 +9,7 @@ public interface WaitStrategy { * Returns the time, in milliseconds, to sleep before retrying. * * @param failedAttempt the previous failed {@code Attempt} - * @return the sleep time before next attempt + * @return the sleep time before the next attempt */ long computeSleepTime(Attempt failedAttempt); }