📚 Update SASL documentation

Author: nevans

lib/net/imap.rb

@@ -1242,6 +1242,9 @@ def starttls(**options)
     # +SASL-IR+ capability, below).  Defaults to the #config value for
     # {sasl_ir}[rdoc-ref:Config#sasl_ir], which defaults to +true+.
     #
+    # The +registry+ kwarg can be used to select the mechanism implementation
+    # from a custom registry.  See SASL.authenticator and SASL::Authenticators.
+    #
     # All other arguments are forwarded to the registered SASL authenticator for
     # the requested mechanism.  <em>The documentation for each individual
     # mechanism must be consulted for its specific parameters.</em>

lib/net/imap/sasl.rb

@@ -159,7 +159,10 @@ def initialize(response, message = "authentication ended prematurely")
       # Returns the default global SASL::Authenticators instance.
       def self.authenticators; @authenticators ||= Authenticators.new end
 
-      # Delegates to <tt>registry.new</tt>  See Authenticators#new.
+      # Creates a new SASL authenticator, using SASL::Authenticators#new.
+      #
+      # +registry+ defaults to SASL.authenticators.  All other arguments are
+      # forwarded to to <tt>registry.new</tt>.
       def self.authenticator(*args, registry: authenticators, **kwargs, &block)
         registry.new(*args, **kwargs, &block)
       end

lib/net/imap/sasl/authentication_exchange.rb

@@ -10,38 +10,68 @@ module SASL
       # TODO: raise an error if the command succeeds after being canceled.
       # TODO: use with more clients, to verify the API can accommodate them.
       #
-      # Create an AuthenticationExchange from a client adapter and a mechanism
-      # authenticator:
-      #     def authenticate(mechanism, ...)
-      #       authenticator = SASL.authenticator(mechanism, ...)
-      #       SASL::AuthenticationExchange.new(
-      #         sasl_adapter, mechanism, authenticator
-      #       ).authenticate
-      #     end
-      #
-      #     private
+      # An AuthenticationExchange represents a single attempt to authenticate
+      # a SASL client to a SASL server.  It is created from a client adapter, a
+      # mechanism name, and a mechanism authenticator.  When #authenticate is
+      # called, it will send the appropriate authenticate command to the server,
+      # returning the client response on success and raising an exception on
+      # failure.
       #
-      #     def sasl_adapter = MyClientAdapter.new(self, &method(:send_command))
+      # In most cases, the client will not need to use
+      # SASL::AuthenticationExchange directly at all.  Instead, use
+      # SASL::ClientAdapter#authenticate.  If customizations are needed, the
+      # custom client adapter is probably the best place for that code.
       #
-      # Or delegate creation of the authenticator to ::build:
       #     def authenticate(...)
-      #       SASL::AuthenticationExchange.build(sasl_adapter, ...)
-      #         .authenticate
+      #       MyClient::SASLAdapter.new(self).authenticate(...)
       #     end
       #
-      # As a convenience, ::authenticate combines ::build and #authenticate:
+      # SASL::ClientAdapter#authenticate delegates to ::authenticate, like so:
+      #
       #     def authenticate(...)
+      #       sasl_adapter = MyClient::SASLAdapter.new(self)
       #       SASL::AuthenticationExchange.authenticate(sasl_adapter, ...)
       #     end
       #
-      # Likewise, ClientAdapter#authenticate delegates to #authenticate:
-      #     def authenticate(...) = sasl_adapter.authenticate(...)
+      # ::authenticate simply delegates to ::build and #authenticate, like so:
+      #
+      #     def authenticate(...)
+      #       sasl_adapter = MyClient::SASLAdapter.new(self)
+      #       SASL::AuthenticationExchange
+      #         .build(sasl_adapter, ...)
+      #         .authenticate
+      #     end
+      #
+      # And ::build delegates to SASL.authenticator and ::new, like so:
+      #
+      #     def authenticate(mechanism, ...)
+      #       sasl_adapter = MyClient::SASLAdapter.new(self)
+      #       authenticator = SASL.authenticator(mechanism, ...)
+      #       SASL::AuthenticationExchange
+      #         .new(sasl_adapter, mechanism, authenticator)
+      #         .authenticate
+      #     end
       #
       class AuthenticationExchange
         # Convenience method for <tt>build(...).authenticate</tt>
+        #
+        # See also: SASL::ClientAdapter#authenticate
         def self.authenticate(...) build(...).authenticate end
 
-        # Use +registry+ to override the global Authenticators registry.
+        # Convenience method to combine the creation of a new authenticator and
+        # a new Authentication exchange.
+        #
+        # +client+ must be an instance of SASL::ClientAdapter.
+        #
+        # +mechanism+ must be a SASL mechanism name, as a string or symbol.
+        #
+        # +sasl_ir+ allows or disallows sending an "initial response", depending
+        # also on whether the server capabilities, mechanism authenticator, and
+        # client adapter all support it.  Defaults to +true+.
+        #
+        # +mechanism+, +args+, +kwargs+, and +block+ are all forwarded to
+        # SASL.authenticator.  Use the +registry+ kwarg to override the global
+        # SASL::Authenticators registry.
         def self.build(client, mechanism, *args, sasl_ir: true, **kwargs, &block)
           authenticator = SASL.authenticator(mechanism, *args, **kwargs, &block)
           new(client, mechanism, authenticator, sasl_ir: sasl_ir)

lib/net/imap/sasl/client_adapter.rb

@@ -36,7 +36,7 @@ def initialize(client, &command_proc)
         # Delegates to AuthenticationExchange.authenticate.
         def authenticate(...) AuthenticationExchange.authenticate(self, ...) end
 
-        # Do the protocol and server both support an initial response?
+        # Do the protocol, server, and client all support an initial response?
         def sasl_ir_capable?; client.sasl_ir_capable? end
 
         # Does the server advertise support for the mechanism?