📚 Update rdoc for Config and related updates

Author: nevans

lib/net/imap.rb

@@ -767,7 +767,8 @@ class << self
 
     # The client configuration.  See Net::IMAP::Config.
     #
-    # By default, config inherits from the global Net::IMAP.config.
+    # By default, the client's local configuration inherits from the global
+    # Net::IMAP.config.
     attr_reader :config
 
     # Seconds to wait until a connection is opened.
@@ -818,18 +819,20 @@ def idle_response_timeout; config.idle_response_timeout end
     #   SSLContext[https://docs.ruby-lang.org/en/master/OpenSSL/SSL/SSLContext.html].
     #
     # [config]
-    #   A Net::IMAP::Config object to base the client #config on.  By default
-    #   the global Net::IMAP.config is used.  Note that this sets the _parent_
-    #   config object for inheritance.  Every Net::IMAP client has its own
-    #   unique #config for overrides.
+    #   A Net::IMAP::Config object to use as the basis for #config.  By default,
+    #   the global Net::IMAP.config is used.
     #
-    # Any other keyword arguments will be forwarded to Config.new, to create the
-    # client's #config.  For example:
+    #   >>>
+    #     *NOTE:* +config+ does not set #config directly---it sets the _parent_
+    #     config for inheritance.  Every client creates its own unique #config.
     #
-    # [open_timeout]
-    #   Seconds to wait until a connection is opened
-    # [idle_response_timeout]
-    #   Seconds to wait until an IDLE response is received
+    #   All other keyword arguments are forwarded to Net::IMAP::Config.new, to
+    #   initialize the client's #config. For example:
+    #
+    #   [{open_timeout}[rdoc-ref:Config#open_timeout]]
+    #     Seconds to wait until a connection is opened
+    #   [{idle_response_timeout}[rdoc-ref:Config#idle_response_timeout]]
+    #     Seconds to wait until an IDLE response is received
     #
     # See DeprecatedClientOptions.new for deprecated arguments.
     #
@@ -1221,7 +1224,8 @@ def starttls(**options)
     # +mechanism+ is the name of the \SASL authentication mechanism to be used.
     #
     # +sasl_ir+ allows or disallows sending an "initial response" (see the
-    # +SASL-IR+ capability, below).
+    # +SASL-IR+ capability, below).  Defaults to the #config value for
+    # {sasl_ir}[rdoc-ref:Config#sasl_ir], which defaults to +true+.
     #
     # All other arguments are forwarded to the registered SASL authenticator for
     # the requested mechanism.  <em>The documentation for each individual
@@ -2421,7 +2425,8 @@ def enable(*capabilities)
     #
     # Returns the server's response to indicate the IDLE state has ended.
     # Returns +nil+ if the server does not respond to #idle_done within
-    # idle_response_timeout seconds.
+    # {config.idle_response_timeout}[rdoc-ref:Config#idle_response_timeout]
+    # seconds.
     #
     # Related: #idle_done, #noop, #check
     #
@@ -2460,8 +2465,9 @@ def idle(timeout = nil, &response_handler)
 
     # Leaves IDLE, allowing #idle to return.
     #
-    # If the server does not respond within idle_response_timeout, #idle will
-    # return +nil+.
+    # If the server does not respond within
+    # {config.idle_response_timeout}[rdoc-ref:Config#idle_response_timeout]
+    # seconds, #idle will return +nil+.
     #
     # Related: #idle
     def idle_done

lib/net/imap/config.rb

@@ -63,7 +63,7 @@ class Config
       # The default config, which is hardcoded and frozen.
       def self.default; @default end
 
-      # The global config object.
+      # The global config object.  Also available from Net::IMAP.config.
       def self.global; @global end
 
       def self.[](config) # :nodoc: unfinished API
@@ -93,20 +93,27 @@ def self.[](config) # :nodoc: unfinished API
       # Seconds to wait until a connection is opened.
       #
       # If the IMAP object cannot open a connection within this time,
-      # it raises a Net::OpenTimeout exception.  See Net::IMAP.new.
+      # it raises a Net::OpenTimeout exception.
+      #
+      # See Net::IMAP.new.
       #
       # The default value is +30+ seconds.
       attr_accessor :open_timeout, type: Integer
 
       # Seconds to wait until an IDLE response is received, after
-      # the client asks to leave the IDLE state.  See Net::IMAP#idle_done.
+      # the client asks to leave the IDLE state.
+      #
+      # See Net::IMAP#idle and Net::IMAP#idle_done.
       #
       # The default value is +5+ seconds.
       attr_accessor :idle_response_timeout, type: Integer
 
       # :markup: markdown
       #
-      # Whether to use the +SASL-IR+ extension with IMAP#authenticate.
+      # Whether to use the +SASL-IR+ extension when the server and \SASL
+      # mechanism both support it.
+      #
+      # See Net::IMAP#authenticate.
       #
       # | Starting with version | The default value is                     |
       # |-----------------------|------------------------------------------|
@@ -120,11 +127,11 @@ def self.[](config) # :nodoc: unfinished API
       # block.  Valid options are `:warn`, `:raise`, or
       # `:silence_deprecation_warning`.
       #
-      # | Starting with version | The default value is           |
-      # |-----------------------|--------------------------------|
-      # | v0.4.13               | +:silence_deprecation_warning+ |
-      # | v0.5                  | +:warn+                        |
-      # | _eventually_          | +:raise+                       |
+      # | Starting with version   | The default value is           |
+      # |-------------------------|--------------------------------|
+      # | v0.4.13                 | +:silence_deprecation_warning+ |
+      # | v0.5 <em>(planned)</em> | +:warn+                        |
+      # | _eventually_            | +:raise+                       |
       attr_accessor :responses_without_block, type: [
         :silence_deprecation_warning, :warn, :raise,
       ]

lib/net/imap/config/attr_accessors.rb

@@ -5,10 +5,13 @@
 module Net
   class IMAP
     class Config
-
-      # Config values are stored in a struct rather than ivars to simplify:
-      # * ensuring that all config objects share a single object shape
-      # * querying only locally configured values, e.g for inspection.
+      # >>>
+      #   *NOTE:* This module is an internal implementation detail, with no
+      #   guarantee of backward compatibility.
+      #
+      # +attr_accessor+ values are stored in a struct rather than ivars, making
+      # it simpler to ensure that all config objects share a single object
+      # shape.  This also simplifies iteration over all defined attributes.
       module AttrAccessors
         module Macros # :nodoc: internal API
           def attr_accessor(name) AttrAccessors.attr_accessor(name) end

lib/net/imap/config/attr_inheritance.rb

@@ -3,10 +3,25 @@
 module Net
   class IMAP
     class Config
-      # Inheritance forms a singly-linked-list, so lookup will be O(n) on the
-      # number of ancestors.  Without customization, ancestor trees will only be
-      # three or four deep:
-      #     client -> [versioned ->] global -> default
+      # >>>
+      #   *NOTE:* The public methods on this module are part of the stable
+      #   public API of Net::IMAP::Config.  But the module itself is an internal
+      #   implementation detail, with no guarantee of backward compatibility.
+      #
+      # +attr_accessor+ methods will delegate to their #parent when the local
+      # value does not contain an override.  Inheritance forms a singly linked
+      # list, so lookup will be <tt>O(n)</tt> on the number of ancestors.  In
+      # practice, the ancestor chain is not expected to be long.  Without
+      # customization, it is only three deep:
+      # >>>
+      #     IMAP#config → Config.global → Config.default
+      #
+      # When creating a client with the +config+ keyword, for example to use
+      # the appropriate defaults for an application or a library while still
+      # relying on global for configuration of +debug+ or +logger+, most likely
+      # the ancestor chain is still only four deep:
+      # >>>
+      #     IMAP#config → alternate defaults → Config.global → Config.default
       module AttrInheritance
         INHERITED = Module.new.freeze
         private_constant :INHERITED

lib/net/imap/config/attr_type_coercion.rb

@@ -3,7 +3,11 @@
 module Net
   class IMAP
     class Config
-      # Adds a +type+ keyword parameter to +attr_accessor+, which enforces
+      # >>>
+      #   *NOTE:* This module is an internal implementation detail, with no
+      #   guarantee of backward compatibility.
+      #
+      # Adds a +type+ keyword parameter to +attr_accessor+, to enforce that
       # config attributes have valid types, for example: boolean, numeric,
       # enumeration, non-nullable, etc.
       module AttrTypeCoercion