📚 Document CAPABILITY command, using capabilities

Basic IMAP4rev1 capabilities, and using IMAP4rev1 extensions.

Author: nevans

lib/net/imap.rb

@@ -444,6 +444,28 @@ def disconnected?
     # Capability requirements—other than +IMAP4rev1+—are listed in the
     # documentation for each command method.
     #
+    # ===== Basic IMAP4rev1 capabilities
+    #
+    # All IMAP4rev1 servers must include +IMAP4rev1+ in their capabilities list.
+    # All IMAP4rev1 servers must _implement_ the +STARTTLS+,
+    # <tt>AUTH=PLAIN</tt>, and +LOGINDISABLED+ capabilities, and clients must
+    # respect their presence or absence.  See the capabilites requirements on
+    # #starttls, #login, and #authenticate.
+    #
+    # ===== Using IMAP4rev1 extensions
+    #
+    # IMAP4rev1 servers must not activate incompatible behavior until an
+    # explicit client action invokes a capability, e.g. sending a command or
+    # command argument specific to that capability.  Extensions to backward
+    # compatible features, such as response codes or mailbox attributes, might
+    # be sent at any time.
+    #
+    # Invoking capabilities which are unknown to Net::IMAP may cause unexpected
+    # behavior and errors, for example ResponseParseError ill be raised when
+    # backwards-incompatible response syntax is received.  Invoking commands or
+    # command parameters that are unsupported by the server may raise
+    # NoResponseError, BadResponseError, or cause other unexpected behavior.
+    #
     # ===== Caching +CAPABILITY+ responses
     #
     # Servers may send their capability list, unsolicited, using the