📚 Update docs for #sort, #uid_sort, & #thread [🚧 sort_keys]

Author: nevans

lib/net/imap.rb

@@ -1461,8 +1461,13 @@ def uid_move(set, mailbox)
     end
 
     # Sends a {SORT command [RFC5256 §3]}[https://www.rfc-editor.org/rfc/rfc5256#section-3]
-    # to sort messages in the mailbox.  Returns an array of message sequence
-    # numbers.
+    # to search a mailbox for messages that match +search_keys+ and return an
+    # array of message sequence numbers, sorted by +sort_keys+.  +search_keys+
+    # are interpreted the same as for #search.
+    #
+    #--
+    # TODO: describe +sort_keys+
+    #++
     #
     # Related: #uid_sort, #search, #uid_search, #thread, #uid_thread
     #
@@ -1482,7 +1487,9 @@ def sort(sort_keys, search_keys, charset)
     end
 
     # Sends a {UID SORT command [RFC5256 §3]}[https://www.rfc-editor.org/rfc/rfc5256#section-3]
-    # to sort messages in the mailbox.  Returns an array of unique identifiers.
+    # to search a mailbox for messages that match +search_keys+ and return an
+    # array of unique identifiers, sorted by +sort_keys+.  +search_keys+ are
+    # interpreted the same as for #search.
     #
     # Related: #sort, #search, #uid_search, #thread, #uid_thread
     #
@@ -1517,8 +1524,11 @@ def remove_response_handler(handler)
     end
 
     # Sends a {THREAD command [RFC5256 §3]}[https://www.rfc-editor.org/rfc/rfc5256#section-3]
-    # Similar to #search, but returns message sequence numbers in threaded
-    # format, as a ThreadMember tree.  The supported algorithms are:
+    # to search a mailbox and return message sequence numbers in threaded
+    # format, as a ThreadMember tree.  +search_keys+ are interpreted the same as
+    # for #search.
+    #
+    # The supported algorithms are:
     #
     # ORDEREDSUBJECT:: split into single-level threads according to subject,
     #                  ordered by date.