📖 Tweak the ENABLE documentation

Author: nevans

lib/net/imap.rb

@@ -257,11 +257,9 @@ module Net
   # In addition to the universal commands, the following commands are valid in
   # the "_authenticated_" state:
   #
-  #--
-  # - #enable: <em>Not implemented by Net::IMAP, yet.</em>
+  # - #enable: Enables backwards incompatible server extensions.
   #
   #   <em>Requires the +ENABLE+ capability.</em>
-  #++
   # - #select:  Open a mailbox and enter the "_selected_" state.
   # - #examine: Open a mailbox read-only, and enter the "_selected_" state.
   # - #create: Creates a new mailbox.
@@ -331,12 +329,11 @@ module Net
   #
   # Although IMAP4rev2[https://tools.ietf.org/html/rfc9051] is <em>not supported
   # yet</em>, Net::IMAP supports several extensions that have been folded into
-  # it: +IDLE+, +MOVE+, +NAMESPACE+, +UIDPLUS+, and +UNSELECT+.
+  # it: +ENABLE+, +IDLE+, +MOVE+, +NAMESPACE+, +UIDPLUS+, and +UNSELECT+.
   #--
   # TODO: RFC4466, ABNF extensions (automatic support for other extensions)
   # TODO: +ESEARCH+, ExtendedSearchData
   # TODO: +SEARCHRES+,
-  # TODO: +ENABLE+,
   # TODO: +SASL-IR+,
   # TODO: +LIST-EXTENDED+,
   # TODO: +LIST-STATUS+,
@@ -435,6 +432,11 @@ module Net
   # TODO...
   #++
   #
+  # ==== RFC5161: +ENABLE+
+  # Folded into IMAP4rev2[https://tools.ietf.org/html/rfc9051], so it is also
+  # listed with {Core IMAP commands}[rdoc-ref:Net::IMAP@Core+IMAP+commands].
+  # - #enable: Enables backwards incompatible server extensions.
+  #
   #--
   # ==== RFC5182 +SEARCHRES+
   # TODO...
@@ -1882,17 +1884,22 @@ def uid_thread(algorithm, search_keys, charset)
     # Sends an {ENABLE command [RFC5161 §3.2]}[https://www.rfc-editor.org/rfc/rfc5161#section-3.1]
     # {[IMAP4rev2 §6.3.1]}[https://www.rfc-editor.org/rfc/rfc9051#section-6.3.1]
     # to enable the specified extenstions, which may be either an
-    # array or a string.
+    # array or a string.  Returns a list of the extensions that were enabled.
     #
     # Some of the extensions that use ENABLE permit the server to send
     # syntax that this class cannot parse. Caution is advised.
     #
+    # The +ENABLE+ command is only valid in the _authenticated_ state, before
+    # any mailbox is selected.
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +ENABLE+
     # [RFC5161[https://tools.ietf.org/html/rfc5161]] or IMAP4REV2
     # [RFC9051[https://tools.ietf.org/html/rfc9051]].
-
+    #
+    # Additionally, the server capabilities must include a capability matching
+    # each enabled extension (usually the same name as the enabled extension).
     def enable(extensions)
       synchronize do
         send_command("ENABLE #{[extensions].flatten.join(' ')}")