📚 Improve rdoc for Net::IMAP.new ssl: params

Listed a few example SSLContext parameters in the `.new` documentation,
to make it easier for people to upgrade from the deprecated SSL
parameters.

Author: nevans

lib/net/imap.rb

@@ -816,7 +816,22 @@ def idle_response_timeout; config.idle_response_timeout end
     #   If +ssl+ is a hash, it's passed to
     #   {OpenSSL::SSL::SSLContext#set_params}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#method-i-set_params];
     #   the keys are names of attribute assignment methods on
-    #   SSLContext[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html].
+    #   SSLContext[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html].  For example:
+    #
+    #   [{ca_file}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#attribute-i-ca_file]]
+    #     The path to a file containing a PEM-format CA certificate.
+    #   [{ca_path}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#attribute-i-ca_path]]
+    #     The path to a directory containing CA certificates in PEM format.
+    #   [{min_version}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#method-i-min_version-3D]]
+    #     Sets the lower bound on the supported SSL/TLS protocol version. Set to
+    #     an +OpenSSL+ constant such as +OpenSSL::SSL::TLS1_2_VERSION+,
+    #   [{verify_mode}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html#attribute-i-verify_mode]]
+    #     SSL session verification mode.  Valid modes include
+    #     +OpenSSL::SSL::VERIFY_PEER+ and +OpenSSL::SSL::VERIFY_NONE+.
+    #
+    #   See {OpenSSL::SSL::SSLContext}[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html] for other valid SSL context params.
+    #
+    #   See DeprecatedClientOptions.new for deprecated SSL arguments.
     #
     # [config]
     #   A Net::IMAP::Config object to use as the basis for #config.  By default,
@@ -834,7 +849,7 @@ def idle_response_timeout; config.idle_response_timeout end
     #   [{idle_response_timeout}[rdoc-ref:Config#idle_response_timeout]]
     #     Seconds to wait until an IDLE response is received
     #
-    # See DeprecatedClientOptions.new for deprecated arguments.
+    #   See Net::IMAP::Config for other valid options.
     #
     # ==== Examples
     #

lib/net/imap/deprecated_client_options.rb

@@ -16,8 +16,8 @@ module DeprecatedClientOptions
       #
       # ==== Obsolete arguments
       #
-      # Using obsolete arguments does not a warning.  Obsolete arguments will be
-      # deprecated by a future release.
+      # Use of obsolete arguments does not print a warning.  Obsolete arguments
+      # will be deprecated by a future release.
       #
       # If a second positional argument is given and it is a hash (or is
       # convertible via +#to_hash+), it is converted to keyword arguments.