Skip to content

Commit

Permalink
📚 Update rdoc for Config and related updates
Browse files Browse the repository at this point in the history
  • Loading branch information
nevans committed Jun 16, 2024
1 parent 5f12016 commit 05d64a0
Show file tree
Hide file tree
Showing 5 changed files with 68 additions and 33 deletions.
36 changes: 21 additions & 15 deletions lib/net/imap.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
#
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
#
Expand Down Expand Up @@ -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
Expand Down
25 changes: 16 additions & 9 deletions lib/net/imap/config.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 |
# |-----------------------|------------------------------------------|
Expand All @@ -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,
]
Expand Down
11 changes: 7 additions & 4 deletions lib/net/imap/config/attr_accessors.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
23 changes: 19 additions & 4 deletions lib/net/imap/config/attr_inheritance.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 5 additions & 1 deletion lib/net/imap/config/attr_type_coercion.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 05d64a0

Please sign in to comment.