net-imap 0.3.3 → 0.3.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 06bbd5924ea63864096450babeb1bde82f6235fa3542df192c39f0ee134ca7bf
-  data.tar.gz: 959bb6e2a15902bc9422ba55bfc7271d164687ccd344ea297e84ac1933f01e82
+  metadata.gz: 7942e0dcda47ac417806fb03aec58b66b8bac3ccf51f53f2f7ac2c6a588e35af
+  data.tar.gz: 38530b6af862085a9d1ff3c59c6536152acc15bb7d925d8547cd4feebea42872
 SHA512:
-  metadata.gz: de02b12debf1989068fd4df18b074513d7c1fe8744915453a6491633a1d64222b1f1c2eb1f6c2ced6d1b3cddac0b32faf7dc882cd25082ea322656c488539d32
-  data.tar.gz: b25e3dd246cf6f8b4ae1b0fc71c0c1e853f437cc41fd9b31e74516e8c272c73f4fb4228e4adf9fca54c90db7d5b7db93ee914427637968557bbd7ec750ee444f
+  metadata.gz: 5bd29fb28b2b3ed9b1a0589e38f8844c47e671006d50deb4462fe5e8cfd97ad923ef0af3114a094d31cbb5943ff0ac9a15e549e67ac08be68eb04a0915eae67f
+  data.tar.gz: 7562e44288caa3538203d415f4d0b1dc4a44a77428e40c4b44046b86fb26b1abc2a4226229f4f494e54f21240cc96dea9106afded971829ec5873f507adab7c9

data/lib/net/imap/authenticators.rb

@@ -3,22 +3,42 @@
 # Registry for SASL authenticators used by Net::IMAP.
 module Net::IMAP::Authenticators
 
-  # Adds an authenticator for use with Net::IMAP#authenticate.  +auth_type+ is the
+  # Adds an authenticator for Net::IMAP#authenticate to use.  +mechanism+ is the
   # {SASL mechanism}[https://www.iana.org/assignments/sasl-mechanisms/sasl-mechanisms.xhtml]
-  # supported by +authenticator+ (for instance, "+PLAIN+").  The +authenticator+
-  # is an object which defines a +#process+ method to handle authentication with
-  # the server.  See Net::IMAP::PlainAuthenticator, Net::IMAP::LoginAuthenticator,
-  # Net::IMAP::CramMD5Authenticator, and Net::IMAP::DigestMD5Authenticator for
-  # examples.
+  # implemented by +authenticator+ (for instance, <tt>"PLAIN"</tt>).
+  #
+  # The +authenticator+ must respond to +#new+ (or #call), receiving the
+  # authenticator configuration and return a configured authentication session.
+  # The authenticator session must respond to +#process+, receiving the server's
+  # challenge and returning the client's response.
   #
-  # If +auth_type+ refers to an existing authenticator, it will be
-  # replaced by the new one.
+  # See PlainAuthenticator, XOauth2Authenticator, and DigestMD5Authenticator for
+  # examples.
   def add_authenticator(auth_type, authenticator)
     authenticators[auth_type] = authenticator
   end
 
-  # Builds an authenticator for Net::IMAP#authenticate.  +args+ will be passed
-  # directly to the chosen authenticator's +#initialize+.
+  # :call-seq:
+  #   authenticator(mechanism, ...)                            -> authenticator
+  #   authenticator(mech, *creds, **props) {|prop, auth| val } -> authenticator
+  #   authenticator(mechanism, authnid, creds, authzid=nil)    -> authenticator
+  #   authenticator(mechanism, **properties)                   -> authenticator
+  #   authenticator(mechanism) {|propname, authctx| value }    -> authenticator
+  #
+  # Builds a new authentication session context for +mechanism+.
+  #
+  # [Note]
+  #   This method is intended for internal use by connection protocol code only.
+  #   Protocol client users should see refer to their client's documentation,
+  #   e.g. Net::IMAP#authenticate for Net::IMAP.
+  #
+  # The call signatures documented for this method are recommendations for
+  # authenticator implementors.  All arguments (other than +mechanism+) are
+  # forwarded to the registered authenticator's +#new+ (or +#call+) method, and
+  # each authenticator must document its own arguments.
+  #
+  # The returned object represents a single authentication exchange and <em>must
+  # not</em> be reused for multiple authentication attempts.
   def authenticator(mechanism, *authargs, **properties, &callback)
     authenticator = authenticators.fetch(mechanism.upcase) do
       raise ArgumentError, 'unknown auth type - "%s"' % mechanism

data/lib/net/imap/flags.rb

@@ -257,5 +257,6 @@ module Net
     # special use is likely not to be supported.
     TRASH = :Trash
 
+    # :section:
   end
 end

data/lib/net/imap/sasl/stringprep.rb

@@ -26,6 +26,9 @@ module Net::IMAP::SASL
     #
     # Also checks bidirectional characters, when <tt>bidi: true</tt>, which may
     # raise a BidiStringError.
+    #
+    # +profile+ is an optional string which will be added to any exception that
+    # is raised (it does not affect behavior).
     def check_prohibited!(string, *tables, bidi: false, profile: nil)
       tables = TABLE_TITLES.keys.grep(/^C/) if tables.empty?
       tables |= %w[C.8] if bidi
@@ -47,10 +50,11 @@ module Net::IMAP::SASL
     #   RandALCat character MUST be the last character of the string.
     #
     # This is usually combined with #check_prohibited!, so table "C.8" is only
-    # checked when +c_8: true+.
+    # checked when <tt>c_8: true</tt>.
     #
     # Raises either ProhibitedCodepoint or BidiStringError unless all
-    # requirements are met.
+    # requirements are met.  +profile+ is an optional string which will be
+    # added to any exception that is raised (it does not affect behavior).
     def check_bidi!(string, c_8: false, profile: nil)
       check_prohibited!(string, "C.8", profile: profile) if c_8
       if BIDI_FAILS_REQ2.match?(string)