🚚📚 Move SASL authenticators docs

Author: nevans

lib/net/imap.rb

@@ -995,40 +995,19 @@ def starttls(options = {}, verify = true)
     #
     # +mechanism+ is the name of the \SASL authentication mechanism to be used.
     # All other arguments are forwarded to the authenticator for the requested
-    # mechanism.  The listed call signatures are suggestions.  <em>The
-    # documentation for each individual mechanism must be consulted for its
-    # specific parameters.</em>
+    # mechanism.  The listed call signatures are only suggestions.  Each
+    # mechanism's authenticator must be consulted for its own specific
+    # parameters.
+    # >>>
+    #   *Note:* See Net::IMAP::SASL documentation for a list of mechanism
+    #   classes, and links to each mechanism's documentation.
     #
     # An exception Net::IMAP::NoResponseError is raised if authentication fails.
     #
     # Related: #login, #starttls, #auth_capable?, #auth_mechanisms
     #
-    # ==== Supported SASL Mechanisms
-    #
-    # +PLAIN+::     See PlainAuthenticator.
-    #               Login using clear-text username and password.
-    #
-    # +XOAUTH2+::   See XOauth2Authenticator.
-    #               Login using a username and OAuth2 access token.
-    #               Non-standard and obsoleted by +OAUTHBEARER+, but widely
-    #               supported.
-    #
-    # >>>
-    #   *Deprecated:*  <em>Obsolete mechanisms are available for backwards
-    #   compatibility.</em>
-    #
-    #   For +DIGEST-MD5+ see DigestMD5Authenticator.
-    #
-    #   For +LOGIN+, see LoginAuthenticator.
-    #
-    #   For +CRAM-MD5+, see CramMD5Authenticator.
-    #
-    #   <em>Using a deprecated mechanism will print a warning.</em>
-    #
     # See Net::IMAP::Authenticators for information on plugging in
-    # authenticators for other mechanisms.  See the {SASL mechanism
-    # registry}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
-    # for information on these and other SASL mechanisms.
+    # authenticators for other mechanisms.
     #
     # ===== Capabilities
     #

lib/net/imap/sasl.rb

@@ -21,6 +21,35 @@ class IMAP
     #                  /       |    |      \
     #           EXTERNAL   GSSAPI  PLAIN   Other mechanisms ...
     #
+    # == SASL Mechanisms
+    #
+    # See the {SASL mechanism
+    # registry}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
+    # for a list of all SASL mechanisms and their specifications.
+    #
+    # Each mechanism has different properties and requirements.  Please consult
+    # the documentation for the specific mechanisms you are using:
+    #
+    # +PLAIN+::       See PlainAuthenticator.
+    #                 Login using clear-text username and password.
+    #
+    # +XOAUTH2+::     See XOauth2Authenticator.
+    #                 Login using a username and OAuth2 access token.
+    #                 Non-standard and obsoleted by +OAUTHBEARER+, but widely
+    #                 supported.
+    #
+    # === Deprecated mechanisms
+    #
+    # <em>Obsolete mechanisms are available for backwards compatibility.  Using
+    # a deprecated mechanism will print a warning.</em>
+    #
+    # >>>
+    #   For +CRAM-MD5+, see CramMD5Authenticator.
+    #
+    #   For +DIGEST-MD5+ see DigestMD5Authenticator.
+    #
+    #   For +LOGIN+, see LoginAuthenticator.
+    #
     module SASL
 
       stringprep_path = File.expand_path("sasl/stringprep", __dir__)