docs: Polish all documents (#119)

Signed-off-by: Xuanwo <[email protected]>

src/backoff/api.rs

@@ -1,18 +1,18 @@
 use std::fmt::Debug;
 use std::time::Duration;
 
-/// BackoffBuilder is used to build a new backoff.
+/// BackoffBuilder is utilized to construct a new backoff.
 pub trait BackoffBuilder: Debug + Send + Sync + Unpin {
- /// The associated backoff that returned by this builder.
+ /// The associated backoff returned by this builder.
  type Backoff: Backoff;
 
- /// Builder a new backoff via builder.
+ /// Construct a new backoff using the builder.
  fn build(self) -> Self::Backoff;
 }
 
 /// Backoff is an [`Iterator`] that returns [`Duration`].
 ///
-/// - `Some(Duration)` means caller need to `sleep(Duration)` and retry the same request
-/// - `None` means we have reaching the limits, caller needs to return current error instead.
+/// - `Some(Duration)` indicates the caller should `sleep(Duration)` and retry the request.
+/// - `None` indicates the limits have been reached, and the caller should return the current error instead.
 pub trait Backoff: Iterator<Item = Duration> + Send + Sync + Unpin {}
 impl<T> Backoff for T where T: Iterator<Item = Duration> + Debug + Send + Sync + Unpin {}

src/backoff/constant.rs

@@ -2,12 +2,12 @@ use std::time::Duration;
 
 use crate::backoff::BackoffBuilder;
 
-/// ConstantBuilder is used to build [`ConstantBackoff`]
+/// ConstantBuilder is used to create a [`ConstantBackoff`], providing a steady delay with a fixed number of retries.
 ///
 /// # Default
 ///
 /// - delay: 1s
-/// - max times: 3
+/// - max_times: 3
 ///
 /// # Examples
 ///
@@ -49,19 +49,21 @@ impl Default for ConstantBuilder {
 }
 
 impl ConstantBuilder {
- /// Set delay of current backoff.
+ /// Set the delay for the backoff.
  pub fn with_delay(mut self, delay: Duration) -> Self {
  self.delay = delay;
  self
  }
 
- /// Set max times of current backoff.
+ /// Set the maximum duration for the backoff.
  pub fn with_max_times(mut self, max_times: usize) -> Self {
  self.max_times = Some(max_times);
  self
  }
 
- /// Set jitter on
+ /// Set jitter for the backoff.
+ ///
+ /// Jitter is a random value added to the delay to prevent a thundering herd problem.
  pub fn with_jitter(mut self) -> Self {
  self.jitter = true;
  self
@@ -82,7 +84,10 @@ impl BackoffBuilder for ConstantBuilder {
  }
 }
 
-/// ConstantBackoff provides backoff with constant delay and limited times.
+/// ConstantBackoff offers a consistent delay with a limited number of retries.
+///
+/// This backoff strategy is constructed by [`ConstantBuilder`].
+#[doc(hidden)]
 #[derive(Debug)]
 pub struct ConstantBackoff {
  delay: Duration,
@@ -92,17 +97,6 @@ pub struct ConstantBackoff {
  jitter: bool,
 }
 
-impl Default for ConstantBackoff {
- fn default() -> Self {
- Self {
- delay: Duration::from_secs(1),
- max_times: Some(3),
- attempts: 0,
- jitter: false,
- }
- }
-}
-
 impl Iterator for ConstantBackoff {
  type Item = Duration;
 

src/backoff/exponential.rs

@@ -2,7 +2,7 @@ use std::time::Duration;
 
 use crate::backoff::BackoffBuilder;
 
-/// ExponentialBuilder is used to build a [`ExponentialBackoff`]
+/// ExponentialBuilder is used to construct an [`ExponentialBackoff`] that offers delays with exponential retries.
 ///
 /// # Default
 ///
@@ -56,44 +56,44 @@ impl Default for ExponentialBuilder {
 }
 
 impl ExponentialBuilder {
- /// Set jitter of current backoff.
+ /// Set the jitter for the backoff.
  ///
- /// If jitter is enabled, ExponentialBackoff will add a random jitter in `[0, min_delay)
- /// to current delay.
+ /// When jitter is enabled, [`ExponentialBackoff`] will add a random jitter within `(0, min_delay)`
+ /// to the current delay.
  pub fn with_jitter(mut self) -> Self {
  self.jitter = true;
  self
  }
 
- /// Set factor of current backoff.
+ /// Set the factor for the backoff.
  ///
  /// # Panics
  ///
- /// This function will panic if input factor smaller than `1.0`.
+ /// This function will panic if the input factor is less than `1.0`.
  pub fn with_factor(mut self, factor: f32) -> Self {
  debug_assert!(factor >= 1.0, "invalid factor that lower than 1");
 
  self.factor = factor;
  self
  }
 
- /// Set min_delay of current backoff.
+ /// Set the minimum delay for the backoff.
  pub fn with_min_delay(mut self, min_delay: Duration) -> Self {
  self.min_delay = min_delay;
  self
  }
 
- /// Set max_delay of current backoff.
+ /// Set the maximum delay for the backoff.
  ///
- /// Delay will not increasing if current delay is larger than max_delay.
+ /// The delay will not increase if the current delay exceeds the maximum delay.
  pub fn with_max_delay(mut self, max_delay: Duration) -> Self {
  self.max_delay = Some(max_delay);
  self
  }
 
- /// Set max_times of current backoff.
+ /// Set the maximum number of attempts for the current backoff.
  ///
- /// Backoff will return `None` if max times is reaching.
+ /// The backoff will stop if the maximum number of attempts is reached.
  pub fn with_max_times(mut self, max_times: usize) -> Self {
  self.max_times = Some(max_times);
  self
@@ -117,7 +117,10 @@ impl BackoffBuilder for ExponentialBuilder {
  }
 }
 
-/// Exponential backoff implementation.
+/// ExponentialBackoff provides a delay with exponential retries.
+///
+/// This backoff strategy is constructed by [`ExponentialBuilder`].
+#[doc(hidden)]
 #[derive(Debug)]
 pub struct ExponentialBackoff {
  jitter: bool,
@@ -169,6 +172,7 @@ impl Iterator for ExponentialBackoff {
  }
 }
 
+#[inline]
 pub(crate) fn saturating_mul(d: Duration, rhs: f32) -> Duration {
  match Duration::try_from_secs_f32(rhs * d.as_secs_f32()) {
  Ok(v) => v,

src/backoff/fibonacci.rs

@@ -2,7 +2,7 @@ use std::time::Duration;
 
 use crate::backoff::BackoffBuilder;
 
-/// FibonacciBuilder is used to build a [`FibonacciBackoff`]
+/// FibonacciBuilder is used to build a [`FibonacciBackoff`] which offers a delay with Fibonacci-based retries.
 ///
 /// # Default
 ///
@@ -53,32 +53,31 @@ impl Default for FibonacciBuilder {
 }
 
 impl FibonacciBuilder {
- /// Set jitter of current backoff.
+ /// Set the jitter for the backoff.
  ///
- /// If jitter is enabled, FibonacciBackoff will add a random jitter in `[0, min_delay)
- /// to current delay.
+ /// When jitter is enabled, FibonacciBackoff will add a random jitter between `(0, min_delay)` to the delay.
  pub fn with_jitter(mut self) -> Self {
  self.jitter = true;
  self
  }
 
- /// Set min_delay of current backoff.
+ /// Set the minimum delay for the backoff.
  pub fn with_min_delay(mut self, min_delay: Duration) -> Self {
  self.min_delay = min_delay;
  self
  }
 
- /// Set max_delay of current backoff.
+ /// Set the maximum delay for the current backoff.
  ///
- /// Delay will not increasing if current delay is larger than max_delay.
+ /// The delay will not increase if the current delay exceeds the maximum delay.
  pub fn with_max_delay(mut self, max_delay: Duration) -> Self {
  self.max_delay = Some(max_delay);
  self
  }
 
- /// Set max_times of current backoff.
+ /// Set the maximum number of attempts for the current backoff.
  ///
- /// Backoff will return `None` if max times is reaching.
+ /// The backoff will stop if the maximum number of attempts is reached.
  pub fn with_max_times(mut self, max_times: usize) -> Self {
  self.max_times = Some(max_times);
  self
@@ -102,7 +101,10 @@ impl BackoffBuilder for FibonacciBuilder {
  }
 }
 
-/// Fibonacci backoff implementation.
+/// FibonacciBackoff offers a delay with Fibonacci-based retries.
+///
+/// This backoff strategy is constructed by [`FibonacciBuilder`].
+#[doc(hidden)]
 #[derive(Debug)]
 pub struct FibonacciBackoff {
  jitter: bool,

src/blocking_retry.rs

@@ -4,7 +4,7 @@ use std::time::Duration;
 use crate::backoff::BackoffBuilder;
 use crate::Backoff;
 
-/// BlockingRetryable will add retry support for functions.
+/// BlockingRetryable adds retry support for blocking functions.
 ///
 /// For example:
 ///
@@ -43,7 +43,7 @@ use crate::Backoff;
 /// }
 /// ```
 pub trait BlockingRetryable<B: BackoffBuilder, T, E, F: FnMut() -> Result<T, E>> {
- /// Generate a new retry
+ /// Generate a new retry.
  fn retry(self, builder: B) -> BlockingRetry<B::Backoff, T, E, F>;
 }
 
@@ -57,7 +57,7 @@ where
  }
 }
 
-/// Retry struct generated by [`BlockingRetryable`].
+/// Retry structure generated by [`BlockingRetryable`].
 pub struct BlockingRetry<
  B: Backoff,
  T,
@@ -71,6 +71,7 @@ pub struct BlockingRetry<
  notify: NF,
  f: F,
 }
+
 impl<B, T, E, F> BlockingRetry<B, T, E, F>
 where
  B: Backoff,
@@ -96,7 +97,7 @@ where
 {
  /// Set the conditions for retrying.
  ///
- /// If not specified, we treat all errors as retryable.
+ /// If not specified, all errors are considered retryable.
  ///
  /// # Examples
  ///
@@ -128,9 +129,11 @@ where
  }
  }
 
- /// Set to notify for everything retrying.
+ /// Set to notify for all retry attempts.
+ ///
+ /// When a retry happens, the input function will be invoked with the error and the sleep duration before pausing.
  ///
- /// If not specified, this is a no-op.
+ /// If not specified, this operation does nothing.
  ///
  /// # Examples
  ///
@@ -168,7 +171,7 @@ where
 
  /// Call the retried function.
  ///
- /// TODO: implment [`std::ops::FnOnce`] after it stable.
+ /// TODO: implement [`std::ops::FnOnce`] after it stable.
  pub fn call(mut self) -> Result<T, E> {
  loop {
  let result = (self.f)();

src/blocking_retry_with_context.rs

@@ -4,7 +4,7 @@ use std::time::Duration;
 use crate::backoff::BackoffBuilder;
 use crate::Backoff;
 
-/// BlockingRetryableWithContext will add retry support for functions.
+/// BlockingRetryableWithContext adds retry support for blocking functions.
 pub trait BlockingRetryableWithContext<
  B: BackoffBuilder,
  T,
@@ -27,7 +27,7 @@ where
  }
 }
 
-/// Retry struct generated by [`BlockingRetryableWithContext`].
+/// Retry structure generated by [`BlockingRetryableWithContext`].
 pub struct BlockingRetryWithContext<
  B: Backoff,
  T,
@@ -69,6 +69,8 @@ where
  NF: FnMut(&E, Duration),
 {
  /// Set the context for retrying.
+ ///
+ /// Context is used to capture ownership manually to prevent lifetime issues.
  pub fn context(self, context: Ctx) -> BlockingRetryWithContext<B, T, E, Ctx, F, RF, NF> {
  BlockingRetryWithContext {
  backoff: self.backoff,
@@ -81,7 +83,7 @@ where
 
  /// Set the conditions for retrying.
  ///
- /// If not specified, we treat all errors as retryable.
+ /// If not specified, all errors are considered retryable.
  pub fn when<RN: FnMut(&E) -> bool>(
  self,
  retryable: RN,
@@ -95,9 +97,11 @@ where
  }
  }
 
- /// Set to notify for everything retrying.
+ /// Set to notify for all retry attempts.
+ ///
+ /// When a retry happens, the input function will be invoked with the error and the sleep duration before pausing.
  ///
- /// If not specified, this is a no-op.
+ /// If not specified, this operation does nothing.
  pub fn notify<NN: FnMut(&E, Duration)>(
  self,
  notify: NN,
@@ -113,7 +117,7 @@ where
 
  /// Call the retried function.
  ///
- /// TODO: implment [`std::ops::FnOnce`] after it stable.
+ /// TODO: implement [`std::ops::FnOnce`] after it stable.
  pub fn call(mut self) -> (Ctx, Result<T, E>) {
  let mut ctx = self.ctx.take().expect("context must be valid");
  loop {

src/docs/examples/basic.md

@@ -6,7 +6,7 @@ use backon::Retryable;
 use anyhow::Result;
 
 async fn fetch() -> Result<String> {
- Ok("Hello, Workd!".to_string())
+ Ok("Hello, World!".to_string())
 }
 
 #[tokio::main]

src/docs/examples/with_specific_error.md

@@ -6,7 +6,7 @@ use backon::ExponentialBuilder;
 use backon::Retryable;
 
 async fn fetch() -> Result<String> {
- Ok("Hello, Workd!".to_string())
+ Ok("Hello, World!".to_string())
 }
 
 #[tokio::main]

src/docs/mod.rs

@@ -1,3 +1,3 @@
-//! Docs for the backon crate, like examples.
+//! Docs for the backon crate, like [`examples`].
 
 pub mod examples;