Improve docs for tag mismatch

src/client.rs

@@ -176,9 +176,14 @@ pub struct Connection<T: Read + Write> {
 impl<T: Read + Write> Connection<T> {
     /// Manually increment the current tag.
     ///
-    /// This function can be manually executed by callers when the
+    /// If writing a command to the server fails, [`Client`] assumes that the command did not reach
-    /// previous tag was not reused, for example when a timeout did
+    /// the server, and thus that the next tag that should be sent is still the one used for the
-    /// not write anything on the stream.
+    /// failed command. However, it could be the case that the command _did_ reach the server
+    /// before failing, and thus a fresh tag needs to be issued instead.
+    ///
+    /// This function can be used to attempt to manually re-synchronize the client's tag tracker in
+    /// such cases. It forcibly increments the client's tag counter such that the next command
+    /// sent to the server will have a tag that is one greater than it otherwise would.
     pub fn skip_tag(&mut self) {
         self.tag += 1;
     }

src/error.rs

@@ -107,7 +107,8 @@ pub enum Error {
     MissingStatusResponse,
     /// The server responded with a different command tag than the one we just sent.
     ///
-    /// A new session must generally be established to recover from this.
+    /// A new session must generally be established to recover from this. You can also use
+    /// [`Connection::skip_tag`] (which is available through both [`Client`] and [`Session`]).
     TagMismatch(TagMismatch),
     /// StartTls is not available on the server
     StartTlsNotAvailable,