📚 Document the RFC specification for each command [🚧 missing some]

Author: nevans

lib/net/imap.rb

@@ -425,9 +425,10 @@ def disconnected?
       return @sock.closed?
     end
 
-    # Sends a CAPABILITY command, and returns an array of
-    # capabilities that the server supports.  Each capability
-    # is a string.
+    # Sends a {CAPABILITY command [IMAP4rev1
+    # §6.1.1]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.1.1] and returns
+    # an array of capabilities that the server supports.  Each capability is a
+    # string.
     #
     # See the {IANA IMAP4 capabilities
     # registry}[http://www.iana.org/assignments/imap4-capabilities] for a list
@@ -462,8 +463,9 @@ def capability
       end
     end
 
-    # Sends an ID command, and returns a hash of the server's
-    # response, or nil if the server does not identify itself.
+    # Sends an {ID command}[https://tools.ietf.org/html/rfc2971] and returns
+    # a hash of the server's response, or nil if the server does not identify
+    # itself.
     #
     # Note that the user should first check if the server supports the ID
     # capability. For example:
@@ -491,19 +493,25 @@ def id(client_id=nil)
       end
     end
 
-    # Sends a NOOP command to the server. It does nothing.
+    # Sends a {NOOP command [IMAP4rev1
+    # §6.1.2]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.1.2] to the
+    # server.
     def noop
       send_command("NOOP")
     end
 
-    # Sends a LOGOUT command to inform the server that the client is
-    # done with the connection.
+    # 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.
     def logout
       send_command("LOGOUT")
     end
 
-    # Sends a STARTTLS command to start TLS session.
-    # Sends a STARTTLS command to start a TLS session.
+    ##
+    # Sends a {STARTTLS command [IMAP4rev1
+    # §6.2.1]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.1]: to start a
+    # TLS session.
     #
     # ===== Capability
     #
@@ -525,9 +533,12 @@ def starttls(options = {}, verify = true)
       end
     end
 
-    # Sends an AUTHENTICATE command to authenticate the client.
-    # The +auth_type+ parameter is a string that represents
-    # the authentication mechanism to be used. Currently Net::IMAP
+    # Sends an {AUTHENTICATE command [IMAP4rev1
+    # §6.2.2]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.2]) to
+    # authenticate the client.
+    #
+    # The +auth_type+ parameter is a string that
+    # represents the authentication mechanism to be used. Currently Net::IMAP
     # supports the following mechanisms:
     #
     # PLAIN:: Login using cleartext user and password.  Secure with TLS.
@@ -583,10 +594,11 @@ def authenticate(auth_type, *args)
       end
     end
 
-    # Sends a LOGIN command to identify the client and carries
-    # the plaintext +password+ authenticating this +user+.  Note
-    # that, unlike calling #authenticate with an +auth_type+
-    # of "LOGIN", #login does *not* use the login authenticator.
+    # Sends a {LOGIN command [IMAP4rev1
+    # §6.2.3]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.2.3]: to
+    # identify the client and carries the plaintext +password+ authenticating
+    # this +user+.  Note that, unlike calling #authenticate with an +auth_type+
+    # of "LOGIN", #login does *not* use the LoginAuthenticator.
     #
     # A Net::IMAP::NoResponseError is raised if authentication fails.
     #
@@ -601,8 +613,9 @@ def login(user, password)
       send_command("LOGIN", user, password)
     end
 
-    # Sends a SELECT command to select a +mailbox+ so that messages
-    # in the +mailbox+ can be accessed.
+    # Sends a {SELECT command [IMAP4rev1
+    # §6.3.1]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.3.1] to select a
+    # +mailbox+ so that messages in the +mailbox+ can be accessed.
     #
     # After you have selected a mailbox, you may retrieve the number of items in
     # that mailbox from <tt>imap.responses["EXISTS"][-1]</tt>, and the number of
@@ -628,9 +641,11 @@ def select(mailbox)
       end
     end
 
-    # Sends a EXAMINE command to select a +mailbox+ so that messages
-    # in the +mailbox+ can be accessed.  Behaves the same as #select,
-    # except that the selected +mailbox+ is identified as read-only.
+    # Sends a {EXAMINE command [IMAP4rev1
+    # §6.3.2]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.3.2] to select a
+    # +mailbox+ so that messages in the +mailbox+ can be accessed.  Behaves the
+    # same as #select, except that the selected +mailbox+ is identified as
+    # read-only.
     #
     # A Net::IMAP::NoResponseError is raised if the mailbox does not
     # exist or is for some reason non-examinable.
@@ -641,15 +656,19 @@ def examine(mailbox)
       end
     end
 
-    # Sends a CREATE command to create a new +mailbox+.
+    # Sends a {CREATE command [IMAP4rev1
+    # §6.3.3]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.3.3] to create a
+    # new +mailbox+.
     #
     # A Net::IMAP::NoResponseError is raised if a mailbox with that name
     # cannot be created.
     def create(mailbox)
       send_command("CREATE", mailbox)
     end
 
-    # Sends a DELETE command to remove the +mailbox+.
+    # Sends a {DELETE command [IMAP4rev1
+    # §6.3.4]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.3.4] to remove
+    # the +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
@@ -658,8 +677,9 @@ def delete(mailbox)
       send_command("DELETE", mailbox)
     end
 
-    # Sends a RENAME command to change the name of the +mailbox+ to
-    # +newname+.
+    # Sends a {RENAME command [IMAP4rev1
+    # §6.3.5]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.3.5] to change
+    # the name of the +mailbox+ to +newname+.
     #
     # A Net::IMAP::NoResponseError is raised if a mailbox with the
     # name +mailbox+ cannot be renamed to +newname+ for whatever
@@ -988,9 +1008,10 @@ def check
       send_command("CHECK")
     end
 
-    # Sends a CLOSE command to close the currently selected mailbox.
-    # The CLOSE command permanently removes from the mailbox all
-    # messages that have the \Deleted flag set.
+    # Sends a {CLOSE command [IMAP4rev1
+    # §6.4.2]}[https://www.rfc-editor.org/rfc/rfc3501#section-6.4.2] to close
+    # the currently selected mailbox.  The CLOSE command permanently removes
+    # from the mailbox all messages that have the <tt>\\Deleted</tt> flag set.
     def close
       send_command("CLOSE")
     end