📖 Improve #idle and #idle_done rdoc

Author: nevans

lib/net/imap.rb

@@ -2397,11 +2397,16 @@ def enable(*capabilities)
     # checks the connection for each 60 seconds.
     #
     #   loop do
-    #     imap.idle(60) do |res|
-    #       ...
+    #     imap.idle(60) do |response|
+    #       do_something_with(response)
+    #       imap.idle_done if some_condition?(response)
     #     end
     #   end
     #
+    # Returns the server's response to indicate the IDLE state has ended.
+    # Returns +nil+ if the server does not respond to #idle_done within
+    # idle_response_timeout seconds.
+    #
     # Related: #idle_done, #noop, #check
     #
     # ===== Capabilities
@@ -2437,7 +2442,10 @@ def idle(timeout = nil, &response_handler)
       return response
     end
 
-    # Leaves IDLE.
+    # Leaves IDLE, allowing #idle to return.
+    #
+    # If the server does not respond within idle_response_timeout, #idle will
+    # return +nil+.
     #
     # Related: #idle
     def idle_done