Review comments

rustv1/examples/cloudwatchlogs/src/bin/large-query.rs

@@ -243,7 +243,7 @@ mod test {
     use aws_smithy_mocks_experimental::{mock, MockResponseInterceptor, Rule};
     use chrono::{TimeZone, Utc};
 
-    fn from_rules(rules: &[&Rule], enforce_order: bool) -> Client {
+    fn client_from_rules(rules: &[&Rule], enforce_order: bool) -> Client {
         let mut mock_response_interceptor = MockResponseInterceptor::new();
         for rule in rules {
             mock_response_interceptor = mock_response_interceptor.with_rule(rule)
@@ -335,7 +335,7 @@ mod test {
                     .build()
             });
 
-        let client = from_rules(&[&start_query, &small_result], false);
+        let client = client_from_rules(&[&start_query, &small_result], false);
 
         let query = CloudWatchLongQuery::new(client, "testing".into(), date_range.clone());
         // Act: Invoke the large_query method with this range.
@@ -390,7 +390,7 @@ mod test {
                 .build()
         });
 
-        let client = from_rules(&[&get_query_results_0, &get_query_results_1], true);
+        let client = client_from_rules(&[&get_query_results_0, &get_query_results_1], true);
 
         // Arrange: Mock different responses from CloudWatch Logs with varying statuses.
         let query = CloudWatchLongQuery::new(client, "testing".into(), date_range.clone());

rustv1/test-utils/src/waiter.rs

@@ -11,7 +11,7 @@ use tokio;
 // Wait at most 25 seconds.
 const MAX_WAIT: Duration = Duration::from_secs(5 * 60);
 // Wait half a second at a time.
-const POLL_TIME: Duration = Duration::from_millis(500);
+const DEFAULT_INTERVAL: Duration = Duration::from_millis(500);
 
 #[derive(Debug)]
 pub struct WaitError(Duration);
@@ -29,19 +29,22 @@ impl Display for WaitError {
 pub struct Waiter {
     start: SystemTime,
     max: Duration,
-    poll: Duration,
+    interval: Duration,
 }
 
 impl Waiter {
     pub fn builder() -> WaiterBuilder {
         WaiterBuilder::default()
     }
 
-    fn new(max: Duration, poll: Duration) -> Self {
+    /**
+     * *
+     */
+    fn new(max: Duration, interval: Duration) -> Self {
         Waiter {
             start: SystemTime::now(),
             max,
-            poll,
+            interval,
         }
     }
 
@@ -53,15 +56,15 @@ impl Waiter {
         {
             Err(WaitError(self.max))
         } else {
-            tokio::time::sleep(self.poll).await;
+            tokio::time::sleep(self.interval).await;
             Ok(())
         }
     }
 }
 
 impl Default for Waiter {
     fn default() -> Self {
-        Waiter::new(MAX_WAIT, POLL_TIME)
+        Waiter::new(MAX_WAIT, DEFAULT_INTERVAL)
     }
 }
 
@@ -83,18 +86,31 @@ impl WaiterBuilder {
     }
 
     pub fn build(self) -> Waiter {
-        Waiter::new(self.max.unwrap_or(MAX_WAIT), self.poll.unwrap_or(POLL_TIME))
+        Waiter::new(
+            self.max.unwrap_or(MAX_WAIT),
+            self.poll.unwrap_or(DEFAULT_INTERVAL),
+        )
     }
 }
 
 #[macro_export]
 macro_rules! wait_on {
+    // Create an async block to repeat a request until the result of the test is true.
+    // Uses the default Waiter (500ms interval, 25m timeout).
     (
         $req: expr,
         $test: expr
     ) => {
         wait_on!($crate::waiter::Waiter::default(), $req, $test)
     };
+    // Create an async block to repeat a request until the result of the test is true.
+    // The test will work on a completed request - that is, retries, errors, etc will happen before
+    // the test is called. The response is considered done and successful by the SDK.
+    // For example, this can be used to wait for a long-running operation to change to `status: Done|Cancelled`.
+    //
+    // - $waiter is a Waiter used to sleep between attempts, with a maximum timeout.
+    // - $req is an expr that evaluates to an API call that can be `.clone().send().await`ed.
+    // - $test is an expr that should be an Fn which gets passed the successful response of the
     (
         $waiter: expr,
         $req: expr,