📚 Reorganizing capabilities docs

Author: nevans

lib/net/imap.rb

@@ -79,13 +79,55 @@ module Net
   #
   # === Server capabilities and protocol extensions
   #
-  # Net::IMAP <em>does not modify its behavior</em> according to server
-  # #capabilities.  Users of the class must check for required capabilities
-  # before issuing commands.  Special care should be taken to follow all
-  # #capabilities requirements for #starttls, #login, and #authenticate.
+  # Net::IMAP does not _currently_ modify its behaviour according to the
+  # server's advertised #capabilities.  Users of this class must check that the
+  # server is #capable? of extension commands or command arguments before
+  # sending them.  Special care should be taken to follow the #capabilities
+  # requirements for #starttls, #login, and #authenticate.
   #
   # See #capable?, #capabilities, and #capability for more information.
   #
+  # ==== Caching +CAPABILITY+ responses
+  #
+  # When storing the result of #capability be careful to discard the cached
+  # result appropriately, especially following #starttls.  To avoid calling
+  # #capability unnecessarily, call #capable?, #auth_capable?, or #capabilities
+  # to use Net::IMAP's automatic capability caching.
+  #
+  # The server may advertise its initial capabilities using the +CAPABILITY+
+  # ResponseCode in a +PREAUTH+ or +OK+ #greeting.  When TLS has started
+  # (#starttls) and after authentication (#login or #authenticate), the server's
+  # capabilities may change and cached #capabilities are discarded.  The server
+  # may send updated capabilities with an +OK+ TaggedResponse to #login or
+  # #authenticate, and these will be cached by Net::IMAP.  But the
+  # TaggedResponse to #starttls MUST be ignored--it is sent before TLS starts
+  # and is unprotected.
+  #
+  # ==== Basic IMAP4rev1 capabilities
+  #
+  # IMAP4rev1 servers must advertise +IMAP4rev1+ in their capabilities list.
+  # IMAP4rev1 servers must _implement_ the +STARTTLS+, <tt>AUTH=PLAIN</tt>,
+  # and +LOGINDISABLED+ capabilities, and clients must respect their presence
+  # or absence.  See the capabilities requirements on #starttls, #login, and
+  # #authenticate.
+  #
+  # ===== Using IMAP4rev1 extensions
+  #
+  # IMAP4rev1 servers must not activate behavior that is incompatible with the
+  # base specification until an explicit client action invokes a capability,
+  # e.g. sending a command or command argument specific to that capability.
+  # Servers may send data with backward compatible behavior, such as response
+  # codes or mailbox attributes, at any time without client action.
+  #
+  # Invoking capabilities which are unknown to Net::IMAP may cause unexpected
+  # behavior and errors.  For example, ResponseParseError is raised when
+  # unknown response syntax is received.  Invoking commands or command
+  # parameters that are unsupported by the server may raise NoResponseError,
+  # BadResponseError, or cause other unexpected behavior.
+  #
+  # Some capabilities must be explicitly activated using the #enable command.
+  # See #enable for more details.
+  #
   # == Examples of Usage
   #
   # === List sender and subject of all recent messages in the default mailbox
@@ -827,15 +869,15 @@ def disconnected?
     # ensure cache invalidation is handled correctly.
     #
     # >>>
-    #   <em>*NOTE*: Net::IMAP does not </em>currently<em> modify its behaviour
-    #   according to the capabilities of the server.  It is up to the user of
-    #   the class to ensure that a certain capability is supported by a server
-    #   before using it.</em>
+    #   <em>*NOTE:* Net::IMAP does not _currently_ modify its behaviour
+    #   according to the server's advertised capabilities.  Users of this class
+    #   must check that the server is #capable? of extension commands or command
+    #   arguments before sending them.</em>
     #
     #   <em>Capability requirements—other than +IMAP4rev1+—are listed in the
     #   documentation for each command method.</em>
     #
-    # Related: #capable?, #capabilities, #enable
+    # Related: #capable?, #auth_capable?, #capability, #enable
     #
     def capability
       synchronize do
@@ -853,40 +895,15 @@ def capability
     # of all standard capabilities, and their reference RFCs.
     #
     # >>>
-    #   <em>*NOTE*: Net::IMAP does not </em>currently<em> modify its behaviour
-    #   according to the capabilities of the server.  It is up to the user of
-    #   the class to ensure that a certain capability is supported by a server
-    #   before using it.</em>
+    #   <em>*NOTE:* Net::IMAP does not _currently_ modify its behaviour
+    #   according to the server's advertised capabilities.  Users of this class
+    #   must check that the server is #capable? of extension commands or command
+    #   arguments before sending them.</em>
     #
     #   <em>Capability requirements—other than +IMAP4rev1+—are listed in the
     #   documentation for each command method.</em>
     #
-    # Related: #capabilities, #capability, #enable
-    #
-    # ===== Basic IMAP4rev1 capabilities
-    #
-    # IMAP4rev1 servers must include +IMAP4rev1+ in their capabilities list.
-    # IMAP4rev1 servers must _implement_ the +STARTTLS+, <tt>AUTH=PLAIN</tt>,
-    # and +LOGINDISABLED+ capabilities, and clients must respect their presence
-    # or absence.  See the capabilities requirements on #starttls, #login, and
-    # #authenticate.
-    #
-    # ===== Using IMAP4rev1 extensions
-    #
-    # IMAP4rev1 servers must not activate behavior that is incompatible with the
-    # base specification until an explicit client action invokes a capability,
-    # e.g. sending a command or command argument specific to that capability.
-    # Servers may send data with backward compatible behavior, such as response
-    # codes or mailbox attributes, at any time without client action.
-    #
-    # Invoking capabilities which are unknown to Net::IMAP may cause unexpected
-    # behavior and errors.  For example, ResponseParseError is raised when
-    # unknown response syntax is received.  Invoking commands or command
-    # parameters that are unsupported by the server may raise NoResponseError,
-    # BadResponseError, or cause other unexpected behavior.
-    #
-    # Some capabilities must be explicitly activated using the #enable command.
-    # See #enable for more details.
+    # Related: #auth_capable?, #capabilities, #capability, #enable
     #
     # ===== Caching +CAPABILITY+ responses
     #
@@ -902,7 +919,7 @@ def capable?(capability) capabilities.include? capability.to_s.upcase end
     #
     # To ensure case-insensitive capability comparison, use #capable? instead.
     #
-    # Related: #capable?, #capability
+    # Related: #capable?, #auth_capable?, #capability
     def capabilities
       @capabilities || capability
     end