From 9126d3c15b3c557781bfd58f9ce46c53da579ad6 Mon Sep 17 00:00:00 2001
From: Todd Mortimer <todd@opennet.ca>
Date: Tue, 6 Apr 2021 21:54:52 -0400
Subject: [PATCH] Improve documentation around unhandled responses.

UnsolicitedResponse is not exhaustive, and open an issue if you find one
that isn't handled.
---
 src/extensions/idle.rs            | 13 +++++++------
 src/types/unsolicited_response.rs |  7 ++++++-
 2 files changed, 13 insertions(+), 7 deletions(-)

diff --git a/src/extensions/idle.rs b/src/extensions/idle.rs
index 984859b..5be5a07 100644
--- a/src/extensions/idle.rs
+++ b/src/extensions/idle.rs
@@ -193,8 +193,8 @@ impl<'a, T: Read + Write + 'a> Handle<'a, T> {
         }
     }
 
-    /// Block until the given callback returns `Stop`, or until an unhandled
-    /// response arrives on the IDLE channel.
+    /// Block until the given callback returns `Stop`, or until a response
+    /// arrives that is not explicitly handled by [`UnsolicitedResponse`].
     pub fn wait<F>(mut self, callback: F) -> Result<()>
     where
         F: FnMut(UnsolicitedResponse) -> CallbackAction,
@@ -211,8 +211,8 @@ impl<'a, T: SetReadTimeout + Read + Write + 'a> Handle<'a, T> {
         self.keepalive = interval;
     }
 
-    /// Block until the given callback returns `Stop`, or until an unhandled
-    /// response arrives on the IDLE channel.
+    /// Block until the given callback returns `Stop`, or until a response
+    /// arrives that is not explicitly handled by [`UnsolicitedResponse`].
     ///
     /// This method differs from [`Handle::wait`] in that it will periodically refresh the IDLE
     /// connection, to prevent the server from timing out our connection. The keepalive interval is
@@ -235,8 +235,9 @@ impl<'a, T: SetReadTimeout + Read + Write + 'a> Handle<'a, T> {
         self.timed_wait(keepalive, true, callback).map(|_| ())
     }
 
-    /// Block until the given amount of time has elapsed, or the given callback
-    /// returns `Stop`, or until an unhandled response arrives on the IDLE channel.
+    /// Block until the given given amount of time has elapsed, the given callback
+    /// returns `Stop`, or until a response arrives that is not explicitly handled
+    /// by [`UnsolicitedResponse`].
     pub fn wait_with_timeout<F>(self, timeout: Duration, callback: F) -> Result<WaitOutcome>
     where
         F: FnMut(UnsolicitedResponse) -> CallbackAction,
diff --git a/src/types/unsolicited_response.rs b/src/types/unsolicited_response.rs
index 5660089..f755ea2 100644
--- a/src/types/unsolicited_response.rs
+++ b/src/types/unsolicited_response.rs
@@ -12,7 +12,12 @@ use imap_proto::{
 
 /// Responses that the server sends that are not related to the current command.
 /// [RFC 3501](https://tools.ietf.org/html/rfc3501#section-7) states that clients need to be able
-/// to accept any response at any time. These are the ones we've encountered in the wild.
+/// to accept any response at any time.
+///
+/// Not all possible responses are explicitly enumerated here because in practice only
+/// some types of responses are delivered as unsolicited responses. If you encounter an
+/// unsolicited response in the wild that is not handled here, please
+/// [open an issue](https://github.com/jonhoo/rust-imap/issues) and let us know!
 ///
 /// Note that `Recent`, `Exists` and `Expunge` responses refer to the currently `SELECT`ed folder,
 /// so the user must take care when interpreting these.