📚 Add "Related:" rdoc for most Net::IMAP methods

There are a lot of IMAP commands!  This makes it easier to navigate
between them.  Hopefully this makes it easier to learn the IMAP4rev1
protocol and its extensions, as well.

Author: nevans

lib/net/imap.rb

@@ -407,6 +407,8 @@ class << self
     end
 
     # Disconnects from the server.
+    #
+    # Related: #logout
     def disconnect
       return if disconnected?
       begin
@@ -430,6 +432,8 @@ def disconnect
     end
 
     # Returns true if disconnected from the server.
+    #
+    # Related: #logout, #disconnect
     def disconnected?
       return @sock.closed?
     end
@@ -525,20 +529,26 @@ def id(client_id=nil)
 
     # Sends a {NOOP command [IMAP4rev1 §6.1.2]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.1.2]
     # to the server.
+    #
+    # Related: #idle, #check
     def noop
       send_command("NOOP")
     end
 
     # Sends a {LOGOUT command [IMAP4rev1 §6.1.3]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.1.3]
     # to inform the command to inform the server that the client is done with
     # the connection.
+    #
+    # Related: #disconnect
     def logout
       send_command("LOGOUT")
     end
 
     # Sends a {STARTTLS command [IMAP4rev1 §6.2.1]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.1]
     # to start a TLS session.
     #
+    # Related: Net::IMAP.new, #login, #authenticate
+    #
     # ===== Capability
     #
     # The server's capabilities must include +STARTTLS+.
@@ -602,6 +612,8 @@ def starttls(options = {}, verify = true)
     # See Net::IMAP::Authenticators for more information on plugging in your
     # own authenticator.
     #
+    # Related: #login, #starttls
+    #
     # ==== Capabilities
     #
     # Clients MUST NOT attempt to #authenticate or #login when +LOGINDISABLED+
@@ -634,6 +646,8 @@ def authenticate(auth_type, *args)
     #
     # A Net::IMAP::NoResponseError is raised if authentication fails.
     #
+    # Related: #authenticate, #starttls
+    #
     # ==== Capabilities
     # Clients MUST NOT attempt to #authenticate or #login when +LOGINDISABLED+
     # is listed with the capabilities.
@@ -660,6 +674,8 @@ def login(user, password)
     # A Net::IMAP::NoResponseError is raised if the mailbox does not
     # exist or is for some reason non-selectable.
     #
+    # Related: #examine
+    #
     # ===== Capabilities
     #
     # If [UIDPLUS[https://www.rfc-editor.org/rfc/rfc4315.html]] is supported,
@@ -681,6 +697,8 @@ def select(mailbox)
     #
     # A Net::IMAP::NoResponseError is raised if the mailbox does not
     # exist or is for some reason non-examinable.
+    #
+    # Related: #select
     def examine(mailbox)
       synchronize do
         @responses.clear
@@ -693,6 +711,8 @@ def examine(mailbox)
     #
     # A Net::IMAP::NoResponseError is raised if a mailbox with that name
     # cannot be created.
+    #
+    # Related: #rename, #delete
     def create(mailbox)
       send_command("CREATE", mailbox)
     end
@@ -703,6 +723,8 @@ def create(mailbox)
     # A Net::IMAP::NoResponseError is raised if a mailbox with that name
     # cannot be deleted, either because it does not exist or because the
     # client does not have permission to delete it.
+    #
+    # Related: #create, #rename
     def delete(mailbox)
       send_command("DELETE", mailbox)
     end
@@ -714,6 +736,8 @@ def delete(mailbox)
     # name +mailbox+ cannot be renamed to +newname+ for whatever
     # reason; for instance, because +mailbox+ does not exist, or
     # because there is already a mailbox with the name +newname+.
+    #
+    # Related: #create, #delete
     def rename(mailbox, newname)
       send_command("RENAME", mailbox, newname)
     end
@@ -724,6 +748,8 @@ def rename(mailbox, newname)
     #
     # A Net::IMAP::NoResponseError is raised if +mailbox+ cannot be
     # subscribed to; for instance, because it does not exist.
+    #
+    # Related: #unsubscribe, #lsub, #list
     def subscribe(mailbox)
       send_command("SUBSCRIBE", mailbox)
     end
@@ -735,6 +761,8 @@ def subscribe(mailbox)
     # A Net::IMAP::NoResponseError is raised if +mailbox+ cannot be
     # unsubscribed from; for instance, because the client is not currently
     # subscribed to it.
+    #
+    # Related: #subscribe, #lsub, #list
     def unsubscribe(mailbox)
       send_command("UNSUBSCRIBE", mailbox)
     end
@@ -753,7 +781,11 @@ def unsubscribe(mailbox)
     # which mailboxes to match.  If +mailbox+ is empty, the root
     # name of +refname+ and the hierarchy delimiter are returned.
     #
-    # The return value is an array of MailboxList. For example:
+    # The return value is an array of MailboxList.
+    #
+    # Related: #lsub, MailboxList
+    #
+    # ===== For example:
     #
     #   imap.create("foo/bar")
     #   imap.create("foo/baz")
@@ -806,7 +838,9 @@ def list(refname, mailbox)
     # of Namespace objects. These arrays will be empty when the
     # server responds with nil.
     #
-    # For example:
+    # Related: #list, Namespaces, Namespace
+    #
+    # ===== For example:
     #
     #    capabilities = imap.capability
     #    if capabilities.include?("NAMESPACE")
@@ -858,6 +892,8 @@ def namespace
     #        #<Net::IMAP::MailboxList attr=[:Noinferiors, :Marked], delim="/", name="foo/bar">, \\
     #        #<Net::IMAP::MailboxList attr=[:Noinferiors], delim="/", name="foo/baz">]
     #
+    # Related: #list, MailboxList
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +XLIST+,
@@ -879,6 +915,8 @@ def xlist(refname, mailbox)
     # to both admin and user.  If this mailbox exists, it returns an array
     # containing objects of type MailboxQuotaRoot and MailboxQuota.
     #
+    # Related: #getquota, #setquota, MailboxQuotaRoot, MailboxQuota
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +QUOTA+
@@ -898,6 +936,8 @@ def getquotaroot(mailbox)
     # containing a MailboxQuota object is returned.  This command is generally
     # only available to server admin.
     #
+    # Related: #getquotaroot, #setquota, MailboxQuota
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +QUOTA+
@@ -914,6 +954,8 @@ def getquota(mailbox)
     # +quota+ will be unset for that mailbox.  Typically one needs to be logged
     # in as a server admin for this to work.
     #
+    # Related: #getquota, #getquotaroot
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +QUOTA+
@@ -932,6 +974,8 @@ def setquota(mailbox, quota)
     # mailbox.  If +rights+ is nil, then that user will be stripped of any
     # rights to that mailbox.
     #
+    # Related: #getacl
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +ACL+
@@ -948,6 +992,8 @@ def setacl(mailbox, user, rights)
     # along with a specified +mailbox+.  If this mailbox exists, an array
     # containing objects of MailboxACLItem will be returned.
     #
+    # Related: #setacl, MailboxACLItem
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +ACL+
@@ -965,6 +1011,8 @@ def getacl(mailbox)
     # interpreted as for #list.
     #
     # The return value is an array of MailboxList objects.
+    #
+    # Related: #subscribe, #unsubscribe, #list, MailboxList
     def lsub(refname, mailbox)
       synchronize do
         send_command("LSUB", refname, mailbox)
@@ -1040,6 +1088,8 @@ def append(mailbox, message, flags = nil, date_time = nil)
     # to request a checkpoint of the currently selected mailbox.  This performs
     # implementation-specific housekeeping; for instance, reconciling the
     # mailbox's in-memory and on-disk state.
+    #
+    # Related: #idle, #noop
     def check
       send_command("CHECK")
     end
@@ -1048,6 +1098,8 @@ def check
     # to close the currently selected mailbox.  The CLOSE command permanently
     # removes from the mailbox all messages that have the <tt>\\Deleted</tt>
     # flag set.
+    #
+    # Related: #unselect
     def close
       send_command("CLOSE")
     end
@@ -1058,6 +1110,8 @@ def close
     # "_authenticated_" state.  This is the same as #close, except that
     # <tt>\\Deleted</tt> messages are not removed from the mailbox.
     #
+    # Related: #close
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +UNSELECT+
@@ -1069,6 +1123,8 @@ def unselect
     # Sends an {EXPUNGE command [IMAP4rev1 §6.4.3]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.3]
     # Sends a EXPUNGE command to permanently remove from the currently
     # selected mailbox all messages that have the \Deleted flag set.
+    #
+    # Related: #uid_expunge
     def expunge
       synchronize do
         send_command("EXPUNGE")
@@ -1095,6 +1151,8 @@ def expunge
     #        #responses and this method returns them as an array of
     #        <em>sequence number</em> integers.
     #
+    # Related: #expunge
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +UIDPLUS+
@@ -1112,6 +1170,8 @@ def uid_expunge(uid_set)
     # string holding the entire search string, or a single-dimension array of
     # search keywords and arguments.
     #
+    # Related: #uid_search
+    #
     # ===== Search criteria
     #
     # The following are some common search criteria;
@@ -1183,7 +1243,9 @@ def uid_search(keys, charset = nil)
     # The return value is an array of FetchData or nil
     # (instead of an empty array) if there is no matching message.
     #
-    # For example:
+    # Related: #uid_search, FetchData
+    #
+    # ===== For example:
     #
     #   p imap.fetch(6..8, "UID")
     #   #=> [#<Net::IMAP::FetchData seqno=6, attr={"UID"=>98}>, \\
@@ -1209,6 +1271,8 @@ def fetch(set, attr, mod = nil)
     #
     # Similar to #fetch, but the +set+ parameter contains unique identifiers
     # instead of message sequence numbers.
+    #
+    # Related: #fetch, FetchData
     def uid_fetch(set, attr, mod = nil)
       return fetch_internal("UID FETCH", set, attr, mod)
     end
@@ -1221,7 +1285,11 @@ def uid_fetch(set, attr, mod = nil)
     # provided one, '+FLAGS' will add the provided flags, and '-FLAGS' will
     # remove them.  +flags+ is a list of flags.
     #
-    # The return value is an array of FetchData. For example:
+    # The return value is an array of FetchData
+    #
+    # Related: #uid_store
+    #
+    # ===== For example:
     #
     #   p imap.store(6..8, "+FLAGS", [:Deleted])
     #   #=> [#<Net::IMAP::FetchData seqno=6, attr={"FLAGS"=>[:Seen, :Deleted]}>, \\
@@ -1237,6 +1305,8 @@ def store(set, attr, flags)
     #
     # Similar to #store, but +set+ contains unique identifiers instead of
     # message sequence numbers.
+    #
+    # Related: #store
     def uid_store(set, attr, flags)
       return store_internal("UID STORE", set, attr, flags)
     end
@@ -1246,6 +1316,8 @@ def uid_store(set, attr, flags)
     # +mailbox+. The +set+ parameter is a number, an array of numbers, or a
     # Range object.  The number is a message sequence number.
     #
+    # Related: #uid_copy
+    #
     # ===== Capabilities
     #
     # If +UIDPLUS+ [RFC4315[https://www.rfc-editor.org/rfc/rfc4315.html]] is
@@ -1275,6 +1347,8 @@ def uid_copy(set, mailbox)
     # +mailbox+. The +set+ parameter is a number, an array of numbers, or a
     # Range object. The number is a message sequence number.
     #
+    # Related: #uid_move
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +MOVE+
@@ -1296,6 +1370,8 @@ def move(set, mailbox)
     #
     # Similar to #move, but +set+ contains unique identifiers.
     #
+    # Related: #move
+    #
     # ===== Capabilities
     #
     # Same as #move: The server's capabilities must include +MOVE+
@@ -1309,6 +1385,8 @@ def uid_move(set, mailbox)
     # to sort messages in the mailbox.  Returns an array of message sequence
     # numbers.
     #
+    # Related: #uid_sort, #search, #uid_search, #thread, #uid_thread
+    #
     # ===== For example:
     #
     #   p imap.sort(["FROM"], ["ALL"], "US-ASCII")
@@ -1327,6 +1405,8 @@ def sort(sort_keys, search_keys, charset)
     # 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.
     #
+    # Related: #sort, #search, #uid_search, #thread, #uid_thread
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +SORT+
@@ -1369,6 +1449,8 @@ def remove_response_handler(handler)
     # Unlike #search, +charset+ is a required argument.  US-ASCII
     # and UTF-8 are sample values.
     #
+    # Related: #uid_thread, #search, #uid_search, #sort, #uid_sort
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +THREAD+
@@ -1381,6 +1463,8 @@ def thread(algorithm, search_keys, charset)
     # Similar to #thread, but returns unique identifiers instead of
     # message sequence numbers.
     #
+    # Related: #thread, #search, #uid_search, #sort, #uid_sort
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +THREAD+
@@ -1406,6 +1490,8 @@ def uid_thread(algorithm, search_keys, charset)
     #     end
     #   end
     #
+    # Related: #idle_done, #noop, #check
+    #
     # ===== Capabilities
     #
     # The server's capabilities must include +IDLE+
@@ -1440,6 +1526,8 @@ def idle(timeout = nil, &response_handler)
     end
 
     # Leaves IDLE.
+    #
+    # Related: #idle
     def idle_done
       synchronize do
         if @idle_done_cond.nil?