More comments to address PR questions

bindings/rust/s2n-tls-tokio/src/lib.rs

@@ -105,6 +105,10 @@ where
     type Output = Result<(), Error>;
 
     fn poll(mut self: Pin<&mut Self>, ctx: &mut Context<'_>) -> Poll<Self::Output> {
+        // Retrieve a result, either from the stored error
+        // or by polling Connection::negotiate().
+        // Connection::negotiate() only completes once,
+        // regardless of how often this method is polled.
         let result = match self.error.take() {
             Some(err) => Err(err),
             None => {
@@ -114,6 +118,12 @@ where
                 }))
             }
         };
+        // If the result isn't a fatal error, return it immediately.
+        // Otherwise, poll Connection::shutdown().
+        //
+        // Shutdown is only best-effort.
+        // When Connection::shutdown() completes, even with an error,
+        // we return the original Connection::negotiate() error.
         match result {
             Ok(r) => Ok(r).into(),
             Err(e) if e.is_retryable() => Err(e).into(),

bindings/rust/s2n-tls-tokio/tests/shutdown.rs

@@ -114,7 +114,11 @@ async fn shutdown_with_blinding() -> Result<(), Box<dyn std::error::Error>> {
     );
     assert!(timeout.is_err());
 
-    // Shutdown MUST eventually gracefully complete after blinding
+    // Shutdown MUST eventually complete after blinding.
+    //
+    // We check for completion, but not for success. At the moment, the
+    // call to s2n_shutdown will fail. See `shutdown_with_blinding_slow()`
+    // for verification that s2n_shutdown eventually suceeds.
     let (timeout, _) = join!(
         time::timeout(common::MAX_BLINDING_SECS, server.shutdown()),
         time::timeout(common::MAX_BLINDING_SECS, read_until_shutdown(&mut client)),

bindings/rust/s2n-tls/src/raw/error.rs

@@ -73,15 +73,17 @@ impl Fallible for isize {
 impl Fallible for u64 {
     type Output = Self;
 
-    /// Converts a u64 to a Result by checking for the maximum value.
+    /// Converts a u64 to a Result by checking for u64::MAX.
     ///
     /// If a method that returns an unsigned int is fallible,
-    /// then the -1 error result wraps around to the maximum value.
-    /// The maximum value must not be possible otherwise.
+    /// then the -1 error result wraps around to u64::MAX.
     ///
-    /// For example, [`s2n_connection_get_delay`] can't return
-    /// the maximum value because s2n-tls blinding delays are limited
-    /// to 30s, or a return value of 3^10.
+    /// For a u64 to be Fallible, a result of u64::MAX must not be
+    /// possible without an error. For example, [`s2n_connection_get_delay`]
+    /// can't return u64::MAX as a valid result because
+    /// s2n-tls blinding delays are limited to 30s, or a return value of 3^10 ns,
+    /// which is significantly less than u64::MAX. [`s2n_connection_get_delay`]
+    /// would therefore only return u64::MAX for a -1 error result.
     fn into_result(self) -> Result<Self::Output, Error> {
         if self != Self::MAX {
             Ok(self)