From 45a8fcf27e3a7d1b79338c53779c3a7dc17e3aca Mon Sep 17 00:00:00 2001
From: Christian Krause <christian.krause@mailbox.org>
Date: Sun, 21 Jun 2020 11:39:57 +0200
Subject: [PATCH] Add note about server greeting to Client::new

---
 src/client.rs | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/src/client.rs b/src/client.rs
index a640668..33f5d1a 100644
--- a/src/client.rs
+++ b/src/client.rs
@@ -240,6 +240,29 @@ impl<T: Read + Write> Client<T> {
     ///
     /// This method primarily exists for writing tests that mock the underlying transport, but can
     /// also be used to support IMAP over custom tunnels.
+    ///
+    /// **Note:** In case you do need to use `Client::new` over `imap::connect`, you will need to
+    /// listen for the IMAP protocol server greeting before authenticating:
+    ///
+    /// ```rust,no_run
+    /// # extern crate imap;
+    /// # extern crate native_tls;
+    /// # use imap::Client;
+    /// # use native_tls::TlsConnector;
+    /// # use std::io;
+    /// # use std::net::TcpStream;
+    /// # fn main() {
+    /// # let server = "imap.example.com";
+    /// # let username = "";
+    /// # let password = "";
+    /// # let tcp = TcpStream::connect((server, 993)).unwrap();
+    /// # let ssl_connector = TlsConnector::builder().build().unwrap();
+    /// # let tls = TlsConnector::connect(&ssl_connector, server.as_ref(), tcp).unwrap();
+    /// let mut client = Client::new(tls);
+    /// client.read_greeting().unwrap();
+    /// let session = client.login(username, password).unwrap();
+    /// # }
+    /// ```
     pub fn new(stream: T) -> Client<T> {
         Client {
             conn: Connection {