📚 Document relevant capabilities for each command

also update existing docs to be consistent with the new format.

Author: nevans

lib/net/imap.rb

@@ -428,16 +428,33 @@ def disconnected?
     # Sends a CAPABILITY command, and returns an array of
     # capabilities that the server supports.  Each capability
     # is a string.
-    # See the {IANA IMAP capabilities registry}[https://www.iana.org/assignments/imap-capabilities/imap-capabilities.xhtml]
-    # for a list of possible capabilities and their RFCs.
+    #
+    # See the {IANA IMAP4 capabilities
+    # registry}[http://www.iana.org/assignments/imap4-capabilities] for a list
+    # of all standard capabilities, and their reference RFCs.
     #
     # >>>
-    #   <em>*Note* that the Net::IMAP class does not modify its
+    #   <em>*Note* that Net::IMAP does not currently 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>
     #
+    # Capability requirements—other than +IMAP4rev1+—are listed in the
+    # documentation for each command method.
+    #
+    # ===== Caching +CAPABILITY+ responses
+    #
+    # Servers may send their capability list, unsolicited, using the
+    # +CAPABILITY+ response code or an untagged +CAPABILITY+ response.  These
+    # responses can be retrieved and cached using #responses or
+    # #add_response_handler.
+    #
+    # But cached capabilities must be discarded after #starttls, #login, or
+    # #authenticate.  The OK TaggedResponse to #login and #authenticate may
+    # include +CAPABILITY+ response code data, but the TaggedResponse for
+    # #starttls is sent clear-text and cannot be trusted.
+    #
     def capability
       synchronize do
         send_command("CAPABILITY")
@@ -462,6 +479,11 @@ def capability
     #    end
     #
     # See [ID[https://tools.ietf.org/html/rfc2971]] for field definitions.
+    #
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +ID+
+    # [RFC2971[https://tools.ietf.org/html/rfc2971]]
     def id(client_id=nil)
       synchronize do
         send_command("ID", ClientID.new(client_id))
@@ -481,6 +503,14 @@ def logout
     end
 
     # Sends a STARTTLS command to start TLS session.
+    # Sends a STARTTLS command to start a TLS session.
+    #
+    # ===== Capability
+    #
+    # The server's capabilities must include +STARTTLS+.
+    #
+    # Server capabilities change after #starttls, #login, and #authenticate. so
+    # Cached capabilities must be invalidated after this method completes.
     def starttls(options = {}, verify = true)
       send_command("STARTTLS") do |resp|
         if resp.kind_of?(TaggedResponse) && resp.name == "OK"
@@ -529,6 +559,18 @@ def starttls(options = {}, verify = true)
     #
     # See Net::IMAP::Authenticators for more information on plugging in your
     # own authenticator.
+    #
+    # ==== Capabilities
+    #
+    # Clients MUST NOT attempt to #authenticate or #login when +LOGINDISABLED+
+    # is listed with the capabilities.
+    #
+    # Clients MUST NOT attempt to authenticate with a mechanism unless
+    # <tt>"AUTH=#{mechanism}"</tt> for that mechanism is a server capability.
+    #
+    # Server capabilities may change after #starttls, #login, and #authenticate.
+    # Any cached capabilities must be invalidated when this method completes.
+    #
     def authenticate(auth_type, *args)
       authenticator = self.class.authenticator(auth_type, *args)
       send_command("AUTHENTICATE", auth_type) do |resp|
@@ -547,6 +589,14 @@ def authenticate(auth_type, *args)
     # of "LOGIN", #login does *not* use the login authenticator.
     #
     # A Net::IMAP::NoResponseError is raised if authentication fails.
+    #
+    # ==== Capabilities
+    # Clients MUST NOT attempt to #authenticate or #login when +LOGINDISABLED+
+    # is listed with the capabilities.
+    #
+    # Server capabilities may change after #starttls, #login, and #authenticate.
+    # Cached capabilities must be invalidated when this method completes.
+    #
     def login(user, password)
       send_command("LOGIN", user, password)
     end
@@ -717,7 +767,10 @@ def list(refname, mailbox)
     #      end
     #    end
     #
-    # The NAMESPACE extension is described in [NAMESPACE[https://tools.ietf.org/html/rfc2342]]
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +NAMESPACE+
+    # [RFC2342[https://tools.ietf.org/html/rfc2342]]
     def namespace
       synchronize do
         send_command("NAMESPACE")
@@ -750,6 +803,16 @@ def namespace
     #   #=> [#<Net::IMAP::MailboxList attr=[:Noselect], delim="/", name="foo/">, \\
     #        #<Net::IMAP::MailboxList attr=[:Noinferiors, :Marked], delim="/", name="foo/bar">, \\
     #        #<Net::IMAP::MailboxList attr=[:Noinferiors], delim="/", name="foo/baz">]
+    #
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +XLIST+,
+    # a deprecated Gmail extension (replaced by +SPECIAL-USE+).
+    #--
+    # TODO: Net::IMAP doesn't yet have full SPECIAL-USE support.  Supporting
+    # servers MAY return SPECIAL-USE attributes, but are not *required* to
+    # unless the SPECIAL-USE return option is supplied.
+    #++
     def xlist(refname, mailbox)
       synchronize do
         send_command("XLIST", refname, mailbox)
@@ -762,7 +825,10 @@ def xlist(refname, mailbox)
     # If this mailbox exists, it returns an array containing objects of type
     # MailboxQuotaRoot and MailboxQuota.
     #
-    # The QUOTA extension is described in [QUOTA[https://tools.ietf.org/html/rfc2087]]
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +QUOTA+
+    # [RFC2087[https://tools.ietf.org/html/rfc2087]].
     def getquotaroot(mailbox)
       synchronize do
         send_command("GETQUOTAROOT", mailbox)
@@ -778,7 +844,10 @@ def getquotaroot(mailbox)
     # MailboxQuota object is returned.  This
     # command is generally only available to server admin.
     #
-    # The QUOTA extension is described in [QUOTA[https://tools.ietf.org/html/rfc2087]]
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +QUOTA+
+    # [RFC2087[https://tools.ietf.org/html/rfc2087]].
     def getquota(mailbox)
       synchronize do
         send_command("GETQUOTA", mailbox)
@@ -791,7 +860,10 @@ def getquota(mailbox)
     # mailbox.  Typically one needs to be logged in as a server admin
     # for this to work.
     #
-    # The QUOTA extension is described in [QUOTA[https://tools.ietf.org/html/rfc2087]]
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +QUOTA+
+    # [RFC2087[https://tools.ietf.org/html/rfc2087]].
     def setquota(mailbox, quota)
       if quota.nil?
         data = '()'
@@ -805,7 +877,10 @@ def setquota(mailbox, quota)
     # +rights+ that user is to have on that mailbox.  If +rights+ is nil,
     # then that user will be stripped of any rights to that mailbox.
     #
-    # The ACL extension is described in [ACL[https://tools.ietf.org/html/rfc4314]]
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +ACL+
+    # [RFC4314[https://tools.ietf.org/html/rfc4314]].
     def setacl(mailbox, user, rights)
       if rights.nil?
         send_command("SETACL", mailbox, user, "")
@@ -818,7 +893,10 @@ def setacl(mailbox, user, rights)
     # If this mailbox exists, an array containing objects of
     # MailboxACLItem will be returned.
     #
-    # The ACL extension is described in [ACL[https://tools.ietf.org/html/rfc4314]]
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +ACL+
+    # [RFC4314[https://tools.ietf.org/html/rfc4314]].
     def getacl(mailbox)
       synchronize do
         send_command("GETACL", mailbox)
@@ -945,10 +1023,10 @@ def expunge
     #        #responses and this method returns them as an array of
     #        <em>sequence number</em> integers.
     #
-    # ===== Capability requirement
+    # ===== Capabilities
     #
-    # +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]] must be
-    # supported by the server.
+    # The server's capabilities must include +UIDPLUS+
+    # [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]].
     def uid_expunge(uid_set)
       synchronize do
         send_command("UID EXPUNGE", MessageSet.new(uid_set))
@@ -1107,10 +1185,10 @@ def uid_copy(set, mailbox)
     # a number, an array of numbers, or a Range object. The number is
     # a message sequence number.
     #
-    # ===== Capabilities requirements
+    # ===== Capabilities
     #
-    # +MOVE+ [RFC6851[https://tools.ietf.org/html/rfc6851]] must be supported by
-    # the server.
+    # The server's capabilities must include +MOVE+
+    # [RFC6851[https://tools.ietf.org/html/rfc6851]].
     #
     # If +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]] is
     # also supported, the server's response should include a +COPYUID+ response
@@ -1123,11 +1201,11 @@ def move(set, mailbox)
 
     # Similar to #move, but +set+ contains unique identifiers.
     #
-    # ===== Capabilities requirements
+    # ===== Capabilities
     #
-    # Same as #move: +MOVE+ [RFC6851[https://tools.ietf.org/html/rfc6851]] must
-    # be supported by the server.  +UIDPLUS+ also affects #uid_move the same way
-    # it affects #move.
+    # Same as #move: The server's capabilities must include +MOVE+
+    # [RFC6851[https://tools.ietf.org/html/rfc6851]].  +UIDPLUS+ also affects
+    # #uid_move the same way it affects #move.
     def uid_move(set, mailbox)
       copy_internal("UID MOVE", set, mailbox)
     end
@@ -1140,14 +1218,20 @@ def uid_move(set, mailbox)
     #   p imap.sort(["DATE"], ["SUBJECT", "hello"], "US-ASCII")
     #   #=> [6, 7, 8, 1]
     #
-    # The SORT extension is described in [SORT[https://tools.ietf.org/html/rfc5256]].
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +SORT+
+    # [RFC5256[https://tools.ietf.org/html/rfc5256]].
     def sort(sort_keys, search_keys, charset)
       return sort_internal("SORT", sort_keys, search_keys, charset)
     end
 
     # Similar to #sort, but returns an array of unique identifiers.
     #
-    # The SORT extension is described in [SORT[https://tools.ietf.org/html/rfc5256]].
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +SORT+
+    # [RFC5256[https://tools.ietf.org/html/rfc5256]].
     def uid_sort(sort_keys, search_keys, charset)
       return sort_internal("UID SORT", sort_keys, search_keys, charset)
     end
@@ -1185,15 +1269,21 @@ def remove_response_handler(handler)
     # Unlike #search, +charset+ is a required argument.  US-ASCII
     # and UTF-8 are sample values.
     #
-    # The THREAD extension is described in [THREAD[https://tools.ietf.org/html/rfc5256]].
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +THREAD+
+    # [RFC5256[https://tools.ietf.org/html/rfc5256]].
     def thread(algorithm, search_keys, charset)
       return thread_internal("THREAD", algorithm, search_keys, charset)
     end
 
     # Similar to #thread, but returns unique identifiers instead of
     # message sequence numbers.
     #
-    # The THREAD extension is described in [THREAD[https://tools.ietf.org/html/rfc5256]].
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +THREAD+
+    # [RFC5256[https://tools.ietf.org/html/rfc5256]].
     def uid_thread(algorithm, search_keys, charset)
       return thread_internal("UID THREAD", algorithm, search_keys, charset)
     end
@@ -1212,6 +1302,11 @@ def uid_thread(algorithm, search_keys, charset)
     #       ...
     #     end
     #   end
+    #
+    # ===== Capabilities
+    #
+    # The server's capabilities must include +IDLE+
+    # [RFC2177[https://tools.ietf.org/html/rfc2177]].
     def idle(timeout = nil, &response_handler)
       raise LocalJumpError, "no block given" unless response_handler