docs: Polish all documents (#119)

Signed-off-by: Xuanwo <github@xuanwo.io>

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;