From f037ba65cde6f3bcfda0ee044627316fedafdd80 Mon Sep 17 00:00:00 2001 From: nick evans Date: Thu, 14 May 2026 09:31:43 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=E2=9A=A0=EF=B8=8F=20Boost=20visibi?= =?UTF-8?q?lity=20of=20raw=20data=20argument=20warnings?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These methods share some of their argument handling, and this was documented by referencing the method they behaved like. Nevertheless, this warning can easily be missed, and it's important enough to call it out explicitly in every method where it's applicable. --- lib/net/imap.rb | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/lib/net/imap.rb b/lib/net/imap.rb index 242a1d98..12a4964d 100644 --- a/lib/net/imap.rb +++ b/lib/net/imap.rb @@ -2255,6 +2255,7 @@ def uid_expunge(uid_set) # provided as an array or a string. # See {"Argument translation"}[rdoc-ref:#search@Argument+translation] # and {"Search criteria"}[rdoc-ref:#search@Search+criteria], below. + # Please note the warning for when +criteria+ is a String. # # +return+ options control what kind of information is returned about # messages matching the search +criteria+. Specifying +return+ should force @@ -2665,7 +2666,8 @@ def search(...) # backward compatibility) but adds SearchResult#modseq when the +CONDSTORE+ # capability has been enabled. # - # See #search for documentation of parameters. + # See #search for documentation of parameters. Please note the + # warning for when +criteria+ is a String. # # ==== Capabilities # @@ -2751,7 +2753,8 @@ def fetch(...) # {SequenceSet[...]}[rdoc-ref:SequenceSet@Creating+sequence+sets]. # (For message sequence numbers, use #fetch instead.) # - # +attr+ behaves the same as with #fetch. + # +attr+ behaves the same as with #fetch. Please note the #fetch + # warning on the +attr+ argument. # >>> # *Note:* Servers _MUST_ implicitly include the +UID+ message data item as # part of any +FETCH+ response caused by a +UID+ command, regardless of @@ -2963,8 +2966,10 @@ def uid_move(set, mailbox) # Sends a {SORT command [RFC5256 §3]}[https://www.rfc-editor.org/rfc/rfc5256#section-3] # 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. + # array of message sequence numbers, sorted by +sort_keys+. + # + # +search_keys+ are interpreted the same as the +criteria+ argument for + # #search. Please note the #search warning for String +criteria+. # #-- # TODO: describe +sort_keys+ @@ -2989,8 +2994,10 @@ def sort(sort_keys, search_keys, charset) # Sends a {UID SORT command [RFC5256 §3]}[https://www.rfc-editor.org/rfc/rfc5256#section-3] # 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. + # array of unique identifiers, sorted by +sort_keys+. + # + # +search_keys+ are interpreted the same as the +criteria+ argument for + # #search. Please note the #search warning for String +criteria+. # # Related: #sort, #search, #uid_search, #thread, #uid_thread # @@ -3004,8 +3011,10 @@ def uid_sort(sort_keys, search_keys, charset) # Sends a {THREAD command [RFC5256 §3]}[https://www.rfc-editor.org/rfc/rfc5256#section-3] # 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. + # format, as a ThreadMember tree. + # + # +search_keys+ are interpreted the same as the +criteria+ argument for + # #search. Please note the #search warning for String +criteria+. # # The supported algorithms are: # @@ -3031,6 +3040,9 @@ def thread(algorithm, search_keys, charset) # Similar to #thread, but returns unique identifiers instead of # message sequence numbers. # + # +search_keys+ are interpreted the same as the +criteria+ argument for + # #search. Please note the #search warning for String +criteria+. + # # Related: #thread, #search, #uid_search, #sort, #uid_sort # # ==== Capabilities