📚 Improve SASL::{ClientAdapter,ProtocolAdapters} rdoc

Author: nevans

lib/net/imap/sasl/client_adapter.rb

@@ -8,18 +8,26 @@ module SASL
       #
       # TODO: use with more clients, to verify the API can accommodate them.
       #
-      # An abstract base class for implementing a SASL authentication exchange.
-      # Different clients will each have their own adapter subclass, overridden
-      # to match their needs.
+      # Represents the client to a SASL::AuthenticationExchange.  By default,
+      # most methods simply delegate to #client.  Clients should subclass
+      # SASL::ClientAdapter and override methods as needed to match the
+      # semantics of this API to their API.
       #
-      # Although the default implementations _may_ be sufficient, subclasses
-      # will probably need to override some methods.  Additionally, subclasses
-      # may need to include a protocol adapter mixin, if the default
+      # Subclasses should also include a protocol adapter mixin when the default
       # ProtocolAdapters::Generic isn't sufficient.
+      #
+      # === Protocol Requirements
+      #
+      # {RFC4422 §4}[https://www.rfc-editor.org/rfc/rfc4422.html#section-4]
+      # lists requirements for protocol specifications to offer SASL.  Where
+      # possible, ClientAdapter delegates the handling of these requirements to
+      # SASL::ProtocolAdapters.
       class ClientAdapter
         include ProtocolAdapters::Generic
 
         # The client that handles communication with the protocol server.
+        #
+        # Most ClientAdapter methods are simply delegated to #client by default.
         attr_reader :client
 
         # +command_proc+ can used to avoid exposing private methods on #client.
@@ -52,13 +60,9 @@ def initialize(client, &command_proc)
         def authenticate(...) AuthenticationExchange.authenticate(self, ...) end
 
         # Do the protocol, server, and client all support an initial response?
-        #
-        # By default, this simply delegates to <tt>client.sasl_ir_capable?</tt>.
         def sasl_ir_capable?; client.sasl_ir_capable? end
 
-        # Does the server advertise support for the mechanism?
-        #
-        # By default, this simply delegates to <tt>client.auth_capable?</tt>.
+        # Does the server advertise support for the +mechanism+?
         def auth_capable?(mechanism); client.auth_capable?(mechanism) end
 
         # Calls command_proc with +command_name+ (see
@@ -89,15 +93,12 @@ def port;             client.port end
         # Exceptions in this array won't drop the connection.
         def response_errors; [] end
 
-        # Drop the connection gracefully.
-        #
-        # By default, this simply delegates to <tt>client.drop_connection</tt>.
+        # Drop the connection gracefully, sending a "LOGOUT" command as needed.
         def drop_connection;  client.drop_connection end
 
-        # Drop the connection abruptly.
-        #
-        # By default, this simply delegates to <tt>client.drop_connection!</tt>.
+        # Drop the connection abruptly, closing the socket without logging out.
         def drop_connection!; client.drop_connection! end
+
       end
     end
   end

lib/net/imap/sasl/protocol_adapters.rb

@@ -4,14 +4,72 @@ module Net
   class IMAP
     module SASL
 
+      # SASL::ProtocolAdapters modules are meant to be used as mixins for
+      # SASL::ClientAdapter and its subclasses.  Where the client adapter must
+      # be customized for each client library, the protocol adapter mixin
+      # handles \SASL requirements that are part of the protocol specification,
+      # but not specific to any particular client library.  In particular, see
+      # {RFC4422 §4}[https://www.rfc-editor.org/rfc/rfc4422.html#section-4]
+      #
+      # === Interface
+      #
+      # >>>
+      #   NOTE: This API is experimental, and may change.
+      #
+      # - {#command_name}[rdoc-ref:Generic#command_name] -- The name of the
+      #   command used to to initiate an authentication exchange.
+      # - {#service}[rdoc-ref:Generic#service] -- The GSSAPI service name.
+      # - {#encode_ir}[rdoc-ref:Generic#encode_ir]--Encodes an initial response.
+      # - {#decode}[rdoc-ref:Generic#decode] -- Decodes a server challenge.
+      # - {#encode}[rdoc-ref:Generic#encode] -- Encodes a client response.
+      # - {#cancel_response}[rdoc-ref:Generic#cancel_response] -- The encoded
+      #   client response used to cancel an authentication exchange.
+      #
+      # Other protocol requirements of the \SASL authentication exchange are
+      # handled by SASL::ClientAdapter.
+      #
+      # === Included protocol adapters
+      #
+      # - Generic -- a basic implementation of all of the methods listed above.
+      # - IMAP -- An adapter for the IMAP4 protocol.
+      # - SMTP -- An adapter for the \SMTP protocol with the +AUTH+ capability.
+      # - POP  -- An adapter for the POP3  protocol with the +SASL+ capability.
       module ProtocolAdapters
-        # This API is experimental, and may change.
+        # See SASL::ProtocolAdapters@Interface.
         module Generic
+          # The name of the protocol command used to initiate a \SASL
+          # authentication exchange.
+          #
+          # The generic implementation returns <tt>"AUTHENTICATE"</tt>.
           def command_name;     "AUTHENTICATE" end
+
+          # A service name from the {GSSAPI/Kerberos/SASL Service Names
+          # registry}[https://www.iana.org/assignments/gssapi-service-names/gssapi-service-names.xhtml].
+          #
+          # The generic implementation returns <tt>"host"</tt>, which is the
+          # generic GSSAPI host-based service name.
           def service;          "host" end
+
+          # Encodes an initial response string.
+          #
+          # The generic implementation returns the result of #encode, or returns
+          # <tt>"="</tt> when +string+ is empty.
           def encode_ir(string) string.empty? ? "=" : encode(string) end
+
+          # Encodes a client response string.
+          #
+          # The generic implementation returns the Base64 encoding of +string+.
           def encode(string)    [string].pack("m0") end
+
+          # Decodes a server challenge string.
+          #
+          # The generic implementation returns the Base64 decoding of +string+.
           def decode(string)    string.unpack1("m0") end
+
+          # Returns the message used by the client to abort an authentication
+          # exchange.
+          #
+          # The generic implementation returns <tt>"*"</tt>.
           def cancel_response;  "*" end
         end