Apply suggestions from code review

Co-authored-by: Eliza Weisman <[email protected]>

tower/src/retry/mod.rs

@@ -20,15 +20,23 @@ pin_project! {
  ///
  /// # Clone
  ///
- /// This middleware requires that the `Service` is `Clone` due to requirements
- /// of `'static` futures. To easily add `Clone` to your service you can
- /// use the `Buffer` middleware.
+ /// This middleware requires that the inner `Service` implements [`Clone`],
+ /// because the `Service` must be stored in each [`ResponseFuture`] in
+ /// order to retry the request in the event of a failure. If the inner
+ /// `Service` type does not implement `Clone`, the [`Buffer`] middleware
+ /// can be added to make any `Service` cloneable.
  ///
- /// The `Policy` is also required to implement `Clone`. This middleware will
- /// clone the policy for each _request session_. This means one instance
- /// of the policy will exist for one request and its subsequent retries only.
- /// This means the mutable reference is only for that session and if you want
- /// to share data between request sessions then you will need to `Arc<Mutex<...>`.
+ /// [`Buffer`]: crate::buffer::Buffer
+ ///
+ /// The `Policy` must also implement `Clone`. This middleware will
+ /// clone the policy for each _request session_. This means a new clone
+ /// of the policy will be created for each initial request and any subsequent 
+ /// retries of that request. Therefore, any state stored in the `Policy` instance
+ /// is for that request session only. In order to share data across request 
+ /// sessions, that shared state may be stored in an [`Arc`], so that all clones
+ /// of the `Policy` type reference the same instance of the shared state.
+ ///
+ /// [`Arc`]: std::sync::Arc
  #[derive(Clone, Debug)]
  pub struct Retry<P, S> {
  policy: P,

tower/src/retry/policy.rs

@@ -56,7 +56,8 @@ pub trait Policy<Req, Res, E> {
  ///
  /// If the request *should* be retried, return `Some` future that will delay
  /// the next retry of the request. This can be used to sleep for a certain
- /// duration or resolve right away.
+ /// duration, to wait for some external condition to be met before retrying,
+ /// or resolve right away, if the request should be retried immediately.
  ///
  /// ## Mutating Requests
  ///