📚 Document that open_timeout is used for TLS too

Author: nevans

lib/net/imap.rb

@@ -843,7 +843,7 @@ class << self
 
     ##
     # :attr_reader: open_timeout
-    # Seconds to wait until a connection is opened.
+    # Seconds to wait until a connection is opened.  Also used by #starttls.
     # Delegates to {config.open_timeout}[rdoc-ref:Config#open_timeout].
 
     ##
@@ -1341,6 +1341,10 @@ def logout!
     # both successful.  Any error indicates that the connection has not been
     # secured.
     #
+    # After the server agrees to start a TLS connection, this method waits up to
+    # {config.open_timeout}[rdoc-ref:Config#open_timeout] before raising
+    # +Net::OpenTimeout+.
+    #
     # *Note:*
     # >>>
     #   Any #response_handlers added before STARTTLS should be aware that the

lib/net/imap/config.rb

@@ -193,10 +193,13 @@ def self.[](config)
 
       # Seconds to wait until a connection is opened.
       #
+      # Applied separately for establishing TCP connection and starting a TLS
+      # connection.
+      #
       # If the IMAP object cannot open a connection within this time,
       # it raises a Net::OpenTimeout exception.
       #
-      # See Net::IMAP.new.
+      # See Net::IMAP.new and Net::IMAP#starttls.
       #
       # The default value is +30+ seconds.
       attr_accessor :open_timeout, type: Integer