Retry: update docs

typelevel · Nov 25, 2024 · ad61cff · ad61cff
1 parent ddf8bd1
commit ad61cff
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 2 deletions.
diff --git a/std/shared/src/main/scala/cats/effect/std/Retry.scala b/std/shared/src/main/scala/cats/effect/std/Retry.scala
@@ -31,6 +31,49 @@ import scala.reflect.{classTag, ClassTag}
  * Glossary:
  *   - individual delay - the delay between retries
  *   - cumulative delay - the total delay accumulated across all retries
+ *
+ * ==Usage==
+ *
+ * ===Retry on all errors===
+ *
+ * {{{
+ * val policy = Retry
+ *   .exponentialBackoff[IO, Throwable](1.second)
+ *   .withMaxRetries(10)
+ *
+ * // retries 10 times at most using an exponential backoff strategy
+ * IO.raiseError(new RuntimeException("oops")).retry(policy)
+ * }}}
+ *
+ * ===Retry on some errors (e.g. TimeoutException)===
+ *
+ * {{{
+ * val policy = Retry
+ *   .exponentialBackoff[IO, Throwable](1.second)
+ *   .withMaxRetries(10)
+ *   .withErrorMatcher(Retry.ErrorMatcher[IO, Throwable].only[TimeoutException])
+ *
+ * // retries 10 times at most using an exponential backoff strategy
+ * IO.raiseError(new TimeoutException("timeout")).retry(policy)
+ *
+ * // gives up immediately
+ * IO.raiseError(new RuntimeException("oops")).retry(policy)
+ * }}}
+ *
+ * ===Retry on all errors except the TimeoutException===
+ *
+ * {{{
+ * val policy = Retry
+ *   .exponentialBackoff[IO, Throwable](1.second)
+ *   .withMaxRetries(10)
+ *   .withErrorMatcher(Retry.ErrorMatcher[IO, Throwable].except[TimeoutException])
+ *
+ * // retries 10 times at most using an exponential backoff strategy
+ * IO.raiseError(new RuntimeException("oops")).retry(policy)
+ *
+ * // gives up immediately
+ * IO.raiseError(new TimeoutException("timeout")).retry(policy)
+ * }}}
  */
 sealed trait Retry[F[_], E] {
   import Retry.{Decision, ErrorMatcher, Status}

diff --git a/tests/shared/src/test/scala/cats/effect/std/RetrySpec.scala b/tests/shared/src/test/scala/cats/effect/std/RetrySpec.scala
@@ -510,7 +510,7 @@ class RetrySpec extends BaseSpec {
           result <- mtlRetry[F, Errors, Unit](
             io,
             policy,
-            (s, e: Errors, d) => EitherT.liftF(ref.update(_ :+ (s, d, e)))
+            (s, e: Errors, d) => EitherT.liftF(ref.update(_ :+ ((s, d, e))))
           ).value
           attempts <- ref.get
         } yield (result, attempts)
@@ -544,7 +544,7 @@ class RetrySpec extends BaseSpec {
           result <- mtlRetry[F, Errors, Unit](
             io,
             policy,
-            (s, e: Errors, d) => EitherT.liftF(ref.update(_ :+ (s, d, e)))
+            (s, e: Errors, d) => EitherT.liftF(ref.update(_ :+ ((s, d, e))))
           ).value
           attempts <- ref.get
         } yield (result, attempts)