disrb 0.1.2.2 → 0.1.3

data/lib/disrb/logger.rb

@@ -1,79 +1,116 @@
 # frozen_string_literal: true
 
-# Logger2 (class Logger already exists in Ruby)
-# Logging handler with some cool styling
+# Logging handler with some cool styling (called Logger2 because Logger is a built-in Ruby class)
+#
+# When you create an instance of this class, you need to set the verbosity level, and when you run the instance methods,
+# it will follow the set verbosity level. Example: you create a Logger2 instance with verbosity level 3 (warning),
+# only the methods "fatal_error", "error" and "warn" will print to the console. The class methods (start with s_)
+# will always print to the console.
 class Logger2
+  # Creates a new Logger2 instance.
+  #
+  # verbosity_level can be set to:
+  # - 0: No logging.
+  # - 1: Fatal errors only.
+  # - 2: Fatal errors and errors.
+  # - 3: All of the above and warnings.
+  # - 4: All of the above and information messages.
+  # - 5: All of the above and debug messages.
+  # @param verbosity_level [Integer] The verbosity level for the logger to follow.
+  # @return [Logger2] Logger2 instance.
   def initialize(verbosity_level)
     @verbosity_level = verbosity_level
   end
 
+  def self.base(acolor1, acolor2, acolor3, name, message)
+    caller = caller_locations[1]
+    file = caller.path
+    line = caller.lineno
+    location = "#{file}:#{line}"
+    name = name.ljust(14, ' ')
+    acolors = [acolor1, acolor2, acolor3].join(';')
+    "\033[1;38;2;255;255;255;48;2;#{acolors}m | #{name} \033[0m\033[38;2;255;255;255;48;2;44;62;80m" \
+      " #{Time.now.strftime('%Y-%m-%d %H:%M:%S')} at #{location} \033[0m\033[1;38;2;255;255;255;48;2;#{acolors}m" \
+      "  \033[0m \e[38;2;#{acolors}m#{message}\e[0m"
+  end
+
+  # Logs a fatal error to the console if the verbosity level is set to 1 or higher.
+  # @param message [String] The message to log.
+  # @return [nil]
   def fatal_error(message)
     return unless @verbosity_level >= 1
 
-    puts("\033[1;38;2;255;255;255;48;2;192;57;43m | FATAL ERROR    \033[0m\033[38;2;255;255;255;48;2;44;62;80m" \
-         " #{Time.now.strftime('%Y-%m-%d %H:%M:%S')} \033[0m\033[1;38;2;255;255;255;48;2;192;57;43m  \033[0m " \
-         "\e[38;2;192;57;43m#{message}\e[0m")
+    puts(Logger2.base(192, 57, 43, 'FATAL ERROR', message))
   end
 
+  # Logs an error to the console if the verbosity level is set to 2 or higher.
+  # @param message [String] The message to log.
+  # @return [nil]
   def error(message)
     return unless @verbosity_level >= 2
 
-    puts("\033[1;38;2;255;255;255;48;2;243;156;18m | ERROR          \033[0m\033[38;2;255;255;255;48;2;44;62;80m" \
-         " #{Time.now.strftime('%Y-%m-%d %H:%M:%S')} \033[0m\033[1;38;2;255;255;255;48;2;243;156;18m  \033[0m " \
-         "\e[38;2;243;156;18m#{message}\e[0m")
+    puts(Logger2.base(243, 156, 18, 'ERROR', message))
   end
 
+  # Logs a debug message to the console if the verbosity level is set to 5.
+  # @param message [String] The message to log.
+  # @return [nil]
   def debug(message)
     return unless @verbosity_level == 5
 
-    puts("\033[1;38;2;255;255;255;48;2;155;89;182m | DEBUG          \033[0m\033[38;2;255;255;255;48;2;44;62;80m" \
-         " #{Time.now.strftime('%Y-%m-%d %H:%M:%S')} \033[0m\033[1;38;2;255;255;255;48;2;155;89;182m  \033[0m " \
-         "\e[38;2;155;89;182m#{message}\e[0m")
+    puts(Logger2.base(155, 89, 182, 'DEBUG', message))
   end
 
+  # Logs a warning to the console if the verbosity level is set to 3 or higher.
+  # @param message [String] The message to log.
+  # @return [nil]
   def warn(message)
     return unless @verbosity_level >= 3
 
-    puts("\033[1;38;2;255;255;255;48;2;241;196;15m | WARNING        \033[0m\033[38;2;255;255;255;48;2;44;62;80m" \
-         " #{Time.now.strftime('%Y-%m-%d %H:%M:%S')} \033[0m\033[1;38;2;255;255;255;48;2;241;196;15m  \033[0m " \
-         "\e[38;2;241;196;15m#{message}\e[0m")
+    puts(Logger2.base(241, 196, 15, 'WARNING', message))
   end
 
+  # Logs an info message to the console if the verbosity level is set to 4 or higher.
+  # @param message [String] The message to log.
+  # @return [nil]
   def info(message)
     return unless @verbosity_level >= 4
 
-    puts("\033[1;38;2;255;255;255;48;2;76;175;80m | INFORMATION    \033[0m\033[38;2;255;255;255;48;2;44;62;80m" \
-         " #{Time.now.strftime('%Y-%m-%d %H:%M:%S')} \033[0m\033[1;38;2;255;255;255;48;2;76;175;80m  \033[0m " \
-         "\e[38;2;76;175;80m#{message}\e[0m")
+    puts(Logger2.base(76, 175, 80, 'INFORMATION', message))
   end
 
+  # Logs a fatal error to the console
+  # @param message [String] The message to log.
+  # @return [nil]
   def self.s_fatal_error(message)
-    puts("\033[1;38;2;255;255;255;48;2;192;57;43m | FATAL ERROR    \033[0m\033[38;2;255;255;255;48;2;44;62;80m" \
-           " #{Time.now.strftime('%Y-%m-%d %H:%M:%S')} \033[0m\033[1;38;2;255;255;255;48;2;192;57;43m  \033[0m " \
-           "\e[38;2;192;57;43m#{message}\e[0m")
+    puts(base(192, 57, 43, 'FATAL ERROR', message))
   end
 
+  # Logs an error to the console
+  # @param message [String] The message to log.
+  # @return [nil]
   def self.s_error(message)
-    puts("\033[1;38;2;255;255;255;48;2;243;156;18m | ERROR          \033[0m\033[38;2;255;255;255;48;2;44;62;80m" \
-           " #{Time.now.strftime('%Y-%m-%d %H:%M:%S')} \033[0m\033[1;38;2;255;255;255;48;2;243;156;18m  \033[0m " \
-           "\e[38;2;243;156;18m#{message}\e[0m")
+    puts(base(243, 156, 18, 'ERROR', message))
   end
 
+  # Logs a debug message to the console
+  # @param message [String] The message to log.
+  # @return [nil]
   def self.s_debug(message)
-    puts("\033[1;38;2;255;255;255;48;2;155;89;182m | DEBUG          \033[0m\033[38;2;255;255;255;48;2;44;62;80m" \
-           " #{Time.now.strftime('%Y-%m-%d %H:%M:%S')} \033[0m\033[1;38;2;255;255;255;48;2;155;89;182m  \033[0m " \
-           "\e[38;2;155;89;182m#{message}\e[0m")
+    puts(base(155, 89, 182, 'DEBUG', message))
   end
 
+  # Logs a warning to the console
+  # @param message [String] The message to log.
+  # @return [nil]
   def self.s_warn(message)
-    puts("\033[1;38;2;255;255;255;48;2;241;196;15m | WARNING        \033[0m\033[38;2;255;255;255;48;2;44;62;80m" \
-           " #{Time.now.strftime('%Y-%m-%d %H:%M:%S')} \033[0m\033[1;38;2;255;255;255;48;2;241;196;15m  \033[0m " \
-           "\e[38;2;241;196;15m#{message}\e[0m")
+    puts(base(241, 196, 15, 'WARNING', message))
   end
 
+  # Logs an info message to the console
+  # @param message [String] The message to log.
+  # @return [nil]
   def self.s_info(message)
-    puts("\033[1;38;2;255;255;255;48;2;76;175;80m | INFORMATION    \033[0m\033[38;2;255;255;255;48;2;44;62;80m" \
-           " #{Time.now.strftime('%Y-%m-%d %H:%M:%S')} \033[0m\033[1;38;2;255;255;255;48;2;76;175;80m  \033[0m " \
-           "\e[38;2;76;175;80m#{message}\e[0m")
+    puts(base(76, 175, 80, 'INFORMATION', message))
   end
 end

data/lib/disrb/message.rb

@@ -1,8 +1,19 @@
 # frozen_string_literal: true
 
-# DiscordApi
-# The class that contains everything that interacts with the Discord API.
+# Class that contains functions that allow interacting with the Discord API.
 class DiscordApi
+  # Gets the messages in a channel. Returns an array of message objects from newest to oldest on success.
+  # See https://discord.com/developers/docs/resources/message#get-channel-messages
+  #
+  # The before, after, and around parameters are mutually exclusive. Only one of them can be specified.
+  # If more than one of these are specified, all of these will be set to nil and an error will be logged
+  # (depends on the verbosity level set).
+  # @param channel_id [String] The ID of the channel to get messages from.
+  # @param around [String, nil] Gets messages around the specified message ID.
+  # @param before [String, nil] Gets messages before the specified message ID.
+  # @param after [String, nil] Gets messages after the specified message ID.
+  # @param limit [Integer, nil] The maximum number of messages to return. Default 50.
+  # @return [Faraday::Response] The response from the Discord API as a Farday::Response object.
   def get_channel_messages(channel_id, around: nil, before: nil, after: nil, limit: nil)
     options = { around: around, before: before, after: after }
     specified_keys = options.reject { |_k, v| v.nil? }.keys
@@ -29,6 +40,11 @@ class DiscordApi
     response
   end
 
+  # Gets a specific message from a channel. Returns a message object on success.
+  # See https://discord.com/developers/docs/resources/message#get-channel-message
+  # @param channel_id [String] The ID of the channel to get the message from.
+  # @param message_id [String] The ID of the message to get.
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def get_channel_message(channel_id, message_id)
     url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}"
     headers = { 'Authorization': @authorization_header }
@@ -40,11 +56,35 @@ class DiscordApi
     response
   end
 
+  # Creates a message in a channel. Returns the created message object on success.
+  # See https://discord.com/developers/docs/resources/message#create-message
+  # One of content, embeds, sticker_ids, components or poll must be provided. If none of these are provided,
+  # the function will log a warning (depends on the verbosity level set) and return nil
+  # @param channel_id [String] The ID of the channel to create the message in
+  # @param content [String, nil] Message contents (up to 2000 characters)
+  # @param nonce [String, Integer, nil] Can be used to verify if a message was sent (up to 25 characters). The value
+  #   will appear in the message object,
+  # @param tts [TrueClass, FalseClass, nil] Whether the message is a TTS message
+  # @param embeds [Array, nil] Up to 10 rich embeds (up to 6000 characters)
+  # @param allowed_mentions [Hash, nil] Allowed mentions object
+  # @param message_reference [Hash, nil] Message reference object for replies/forwards
+  # @param components [Array, nil] An array of Components to include with the message
+  # @param sticker_ids [Array, nil] IDs of up to 3 stickers in the server to send in the message
+  # @param _files [nil] WORK IN PROGRESS
+  # @param attachments [Array, nil] Attachments objects with filename and description. Practically useless due to
+  #   uploading files not being implemented yet.
+  # @param flags [Integer, nil] Message flags combined as a bitfield.
+  # @param enforce_nonce [TrueClass, FalseClass, nil] If true and a nonce is set, the nonce's uniqueness will be
+  #   checked, if a message with the same nonce already exists from the same author, that message will be returned
+  #   and no new message will be created.
+  # @param poll [Hash, nil] A poll object
+  # @return [Faraday::Response, nil] The response from the Discord API as a Faraday::Response object, or nil if none of
+  #   content, embeds, sticker_ids, components or poll were provided.
   def create_message(channel_id, content: nil, nonce: nil, tts: nil, embeds: nil, allowed_mentions: nil,
-                     message_reference: nil, components: nil, sticker_ids: nil, files: nil, attachments: nil,
+                     message_reference: nil, components: nil, sticker_ids: nil, _files: nil, attachments: nil,
                      flags: nil, enforce_nonce: nil, poll: nil)
-    if content.nil? && embeds.nil? && sticker_ids.nil? && components.nil? && files.nil? && poll.nil?
-      @logger.warn('No content, embeds, sticker ids, components, files or poll provided. Skipping function.')
+    if content.nil? && embeds.nil? && sticker_ids.nil? && components.nil? && poll.nil?
+      @logger.warn('No content, embeds, sticker_ids, components or poll provided. Skipping function.')
       return
     end
     output = {}
@@ -56,7 +96,7 @@ class DiscordApi
     output[:message_reference] = message_reference unless message_reference.nil?
     output[:components] = components unless components.nil?
     output[:sticker_ids] = sticker_ids unless sticker_ids.nil?
-    output[:files] = files unless files.nil?
+    # output[:files] = files unless files.nil?
     output[:attachments] = attachments unless attachments.nil?
     output[:flags] = flags unless flags.nil?
     output[:enforce_nonce] = enforce_nonce unless enforce_nonce.nil?
@@ -71,6 +111,11 @@ class DiscordApi
     response
   end
 
+  # Crossposts a message in an Announcement Channel to all following channels. Returns the crossposted message object on
+  # success. See https://discord.com/developers/docs/resources/message#crosspost-message
+  # @param channel_id [String] The ID of the channel the message to crosspost is located
+  # @param message_id [String] The ID of the message to crosspost
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def crosspost_message(channel_id, message_id)
     url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}/crosspost"
     headers = { 'Authorization': @authorization_header }
@@ -82,55 +127,88 @@ class DiscordApi
     response
   end
 
-  def create_reaction(channel_id, message_id, emoji_id)
-    url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}/reactions/#{emoji_id}/@me"
+  # Create a reaction for the specified message. Returns no content on success.
+  # See https://discord.com/developers/docs/resources/message#create-reaction
+  # @param channel_id [String] The ID of the channel the message is located in
+  # @param message_id [String] The ID of the message to create the reaction for
+  # @param emoji [String] URL encoded emoji to react with, or name:id format for custom emojis
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
+  def create_reaction(channel_id, message_id, emoji)
+    url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}/reactions/#{emoji}/@me"
     headers = { 'Authorization': @authorization_header }
     response = DiscordApi.put(url, nil, headers)
     return response if response.status == 204
 
-    @logger.error("Failed to create reaction with emoji ID #{emoji_id} in channel with ID #{channel_id} " \
+    @logger.error("Failed to create reaction with emoji ID #{emoji} in channel with ID #{channel_id} " \
                     "for message with ID #{message_id}. Response: #{response.body}")
     response
   end
 
-  def delete_own_reaction(channel_id, message_id, emoji_id)
-    url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}/reactions/#{emoji_id}/@me"
+  # Deletes a reaction with the specified emoji for the current user in the specified message. Returns no content on
+  # success. See https://discord.com/developers/docs/resources/message#delete-own-reaction
+  # @param channel_id [String] The ID of the channel the message is located in
+  # @param message_id [String] The ID of the message to delete the reaction for
+  # @param emoji [String] URL encoded emoji to delete, or name:id format for custom emojis
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
+  def delete_own_reaction(channel_id, message_id, emoji)
+    url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}/reactions/#{emoji}/@me"
     headers = { 'Authorization': @authorization_header }
     response = DiscordApi.delete(url, headers)
     return response if response.status == 204
 
-    @logger.error("Failed to delete own reaction with emoji ID #{emoji_id} in channel with ID #{channel_id} " \
+    @logger.error("Failed to delete own reaction with emoji ID #{emoji} in channel with ID #{channel_id} " \
                     "for message with ID #{message_id}. Response: #{response.body}")
     response
   end
 
-  def delete_user_reaction(channel_id, message_id, emoji_id, user_id)
-    url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}/reactions/#{emoji_id}/#{user_id}"
+  # Deletes a reaction with the specified emoji for a user in the specified message. Returns no content on success.
+  # See https://discord.com/developers/docs/resources/message#delete-user-reaction
+  # @param channel_id [String] The ID of the channel the message is located in
+  # @param message_id [String] The ID of the message to delete the reaction for
+  # @param emoji [String] URL encoded emoji to delete, or name:id format for custom emojis
+  # @param user_id [String] The ID of the user to delete the reaction for
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
+  def delete_user_reaction(channel_id, message_id, emoji, user_id)
+    url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}/reactions/#{emoji}/#{user_id}"
     headers = { 'Authorization': @authorization_header }
     response = DiscordApi.delete(url, headers)
     return response if response.status == 204
 
-    @logger.error("Failed to delete user reaction with emoji ID #{emoji_id} in channel with ID #{channel_id} " \
+    @logger.error("Failed to delete user reaction with emoji ID #{emoji} in channel with ID #{channel_id} " \
                     "for message with ID #{message_id} by user with ID #{user_id}. Response: #{response.body}")
     response
   end
 
-  def get_reactions(channel_id, message_id, emoji_id, type: nil, after: nil, limit: nil)
+  # Gets a list of users that reacted with the specified emoji to the specified message. Returns an array of user
+  # objects on success. See https://discord.com/developers/docs/resources/message#get-reactions
+  # @param channel_id [String] The ID of the channel the message is located in
+  # @param message_id [String] The ID of the message to get reactions for
+  # @param emoji [String] URL encoded emoji to get reactions for, or name:id format for custom emojis
+  # @param type [Integer, nil] Type of reaction to return.
+  # @param after [String, nil] Get users after this user ID
+  # @param limit [Integer, nil] Maximum number of users to return (1-100).
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
+  def get_reactions(channel_id, message_id, emoji, type: nil, after: nil, limit: nil)
     query_string_hash = {}
     query_string_hash[:type] = type unless type.nil?
     query_string_hash[:after] = after unless after.nil?
     query_string_hash[:limit] = limit unless limit.nil?
     query_string = DiscordApi.handle_query_strings(query_string_hash)
-    url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}/reactions/#{emoji_id}#{query_string}"
+    url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}/reactions/#{emoji}#{query_string}"
     headers = { 'Authorization': @authorization_header }
     response = DiscordApi.get(url, headers)
     return response if response.status == 200
 
-    @logger.error("Failed to get reactions for emoji with ID #{emoji_id} in channel with ID #{channel_id} " \
+    @logger.error("Failed to get reactions for emoji with ID #{emoji} in channel with ID #{channel_id} " \
                     "for message with ID #{message_id}. Response: #{response.body}")
     response
   end
 
+  # Deletes all reactions on a message. Returns no content on success.
+  # See https://discord.com/developers/docs/resources/message#delete-all-reactions
+  # @param channel_id [String] The ID of the channel the message is located in
+  # @param message_id [String] The ID of the message to delete reactions for
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def delete_all_reactions(channel_id, message_id)
     url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}/reactions"
     headers = { 'Authorization': @authorization_header }
@@ -141,22 +219,45 @@ class DiscordApi
                     ". Response: #{response.body}")
   end
 
-  def delete_all_reactions_for_emoji(channel_id, message_id, emoji_id)
-    url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}/reactions/#{emoji_id}"
+  # Deletes all reactions with the specified emoji on a message. Returns no content on success.
+  # See https://discord.com/developers/docs/resources/message#delete-all-reactions-for-emoji
+  # @param channel_id [String] The ID of the channel the message is located in
+  # @param message_id [String] The ID of the message to delete reactions for
+  # @param emoji [String] URL encoded emoji to delete, or name:id format for custom emojis
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
+  def delete_all_reactions_for_emoji(channel_id, message_id, emoji)
+    url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}/reactions/#{emoji}"
     headers = { 'Authorization': @authorization_header }
     response = DiscordApi.delete(url, headers)
     return response if response.status == 204
 
-    @logger.error("Failed to delete all reactions for emoji with ID #{emoji_id} in channel with ID #{channel_id} for " \
+    @logger.error("Failed to delete all reactions for emoji with ID #{emoji} in channel with ID #{channel_id} for " \
                     "message with ID #{message_id}. Response: #{response.body}")
   end
 
+  # Edits a message. Returns the edited message object on success.
+  # See https://discord.com/developers/docs/resources/message#edit-message
+  #
+  # If none of the optional parameters are provided (modifications), the function will not proceed and return nil.
+  # Since the files parameter is WIP, providing only files will also cause the function to not proceed.
+  # @param channel_id [String] The ID of the channel the message is located in
+  # @param message_id [String] The ID of the message to edit
+  # @param content [String, nil] Message contents (up to 2000 characters)
+  # @param embeds [Array, nil] Up to 10 rich embeds (up to 6000 characters)
+  # @param flags [Integer, nil] Message flags combined as an integer.
+  # @param allowed_mentions [Hash, nil] Allowed mentions object
+  # @param components [Array, nil] An array of Components to include with the message
+  # @param files [nil] WORK IN PROGRESS
+  # @param attachments [Array, nil] Attachments objects with filename and description. Practically useless due to
+  #   uploading files not being implemented yet.
+  # @return [Faraday::Response, nil] The response from the Discord API as a Faraday::Response object, or nil if no
+  #  modifications were provided.
   def edit_message(channel_id, message_id, content: nil, embeds: nil, flags: nil, allowed_mentions: nil,
-                   components: nil, files: nil, payload_json: nil, attachments: nil)
-    if args[2..].all?(&:nil?)
+                   components: nil, files: nil, attachments: nil)
+    if args[2..].all?(&:nil?) || (args[2..].delete(:files).all?(&:nil?) && !files.nil?)
       @logger.warn("No modifications provided for message with ID #{message_id} in channel with ID #{channel_id}. " \
-                     'Skipping function.')
-      return nil
+                     'The files parameter is WIP. Skipping function.')
+      return
     end
     output = {}
     output[:content] = content unless content.nil?
@@ -164,8 +265,7 @@ class DiscordApi
     output[:flags] = flags unless flags.nil?
     output[:allowed_mentions] = allowed_mentions unless allowed_mentions.nil?
     output[:components] = components unless components.nil?
-    output[:files] = files unless files.nil?
-    output[:payload_json] = payload_json unless payload_json.nil?
+    # output[:files] = files unless files.nil?
     output[:attachments] = attachments unless attachments.nil?
     url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}"
     data = JSON.generate(output)
@@ -178,6 +278,12 @@ class DiscordApi
     response
   end
 
+  # Deletes a message. Returns no content on success.
+  # See https://discord.com/developers/docs/resources/message#delete-message
+  # @param channel_id [String] The ID of the channel the message is located in
+  # @param message_id [String] The ID of the message to delete
+  # @param audit_reason [String, nil] The reason for deleting the message. Shows up on the audit log.
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def delete_message(channel_id, message_id, audit_reason = nil)
     url = "#{@base_url}/channels/#{channel_id}/messages/#{message_id}"
     headers = { 'Authorization': @authorization_header }
@@ -190,6 +296,12 @@ class DiscordApi
     response
   end
 
+  # Bulk deletes messages. Returns no content on success.
+  # See https://discord.com/developers/docs/resources/message#bulk-delete-messages
+  # @param channel_id [String] The ID of the channel the messages are located in
+  # @param messages [Array] An array of message IDs (as strings) to delete. (2-100 IDs)
+  # @param audit_reason [String, nil] The reason for deleting the messages. Shows up on the audit log.
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def bulk_delete_messages(channel_id, messages, audit_reason = nil)
     output = { messages: messages }
     url = "#{@base_url}/channels/#{channel_id}/messages/bulk-delete"
@@ -203,6 +315,12 @@ class DiscordApi
     response
   end
 
+  # Gets pinned messages in a channel. See https://discord.com/developers/docs/resources/message#get-channel-pins for
+  #   more info and response structure.
+  # @param channel_id [String] The ID of the channel to get pinned messages from
+  # @param before [String, nil] Get messages pinned before this ISO8601 timestamp
+  # @param limit [Integer, nil] The maximum number of messages to return. (1-50, default 50)
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def get_channel_pins(channel_id, before: nil, limit: nil)
     query_string_hash = {}
     query_string_hash[:before] = before unless before.nil?
@@ -217,6 +335,12 @@ class DiscordApi
     response
   end
 
+  # Pins a message in a channel. Returns no content on success.
+  # See https://discord.com/developers/docs/resources/message#pin-message
+  # @param channel_id [String] The ID of the channel the message is located in
+  # @param message_id [String] The ID of the message to pin
+  # @param audit_reason [String, nil] The reason for pinning the message. Shows up in the audit log.
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def pin_message(channel_id, message_id, audit_reason = nil)
     url = "#{@base_url}/channels/#{channel_id}/messages/pins/#{message_id}"
     headers = { 'Authorization': @authorization_header }
@@ -229,6 +353,12 @@ class DiscordApi
     response
   end
 
+  # Unpins a message in a channel. Returns no content on success.
+  # See https://discord.com/developers/docs/resources/message#unpin-message
+  # @param channel_id [String] The ID of the channel the message is located in
+  # @param message_id [String] The ID of the message to unpin
+  # @param audit_reason [String, nil] The reason for unpinning the message. Shows up in the audit log.
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def unpin_message(channel_id, message_id, audit_reason = nil)
     url = "#{@base_url}/channels/#{channel_id}/messages/pins/#{message_id}"
     headers = { 'Authorization': @authorization_header }

data/lib/disrb/user.rb

@@ -2,9 +2,10 @@
 
 # rubocop:disable Naming/AccessorMethodName
 
-# DiscordApi
-# The class that contains everything that interacts with the Discord API.
+# Class that contains functions that allow interacting with the Discord API.
 class DiscordApi
+  # Returns the user object of the current user. See https://discord.com/developers/docs/resources/user#get-current-user
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def get_current_user
     url = "#{@base_url}/users/@me"
     headers = { 'Authorization': @authorization_header }
@@ -15,6 +16,9 @@ class DiscordApi
     response
   end
 
+  # Returns the user object of the specified user. See https://discord.com/developers/docs/resources/user#get-user
+  # @param user_id [String] The ID of the user.
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def get_user(user_id)
     url = "#{@base_url}/users/#{user_id}"
     headers = { 'Authorization': @authorization_header }
@@ -25,11 +29,15 @@ class DiscordApi
     response
   end
 
+  # Modifies the current user. See https://discord.com/developers/docs/resources/user#modify-current-user
+  #
+  # If none of the parameters are provided, the function will not proceed and return nil.
+  # @param username [String, nil] The new username for the current user. May cause discriminator to be randomized.
+  # @param avatar [String, nil] The new avatar for the current user. See https://discord.com/developers/docs/reference#image-data
+  # @param banner [String, nil] The new banner for the current user. See https://discord.com/developers/docs/reference#image-data
+  # @return [Faraday::Response, nil] The response from the Discord API as a Faraday::Response object or nil if no
+  #   modifications were provided.
   def modify_current_user(username: nil, avatar: nil, banner: nil)
-    if args.all?(&:nil?)
-      @logger.warn('No modifications provided for current user. Skipping function.')
-      return nil
-    end
     output = {}
     output[:username] = username unless username.nil?
     output[:avatar] = avatar unless avatar.nil?
@@ -48,6 +56,14 @@ class DiscordApi
     response
   end
 
+  # Returns an array of (partial) guild objects that the current user is a member of.
+  # See https://discord.com/developers/docs/resources/user#get-current-user-guilds
+  # @param before [String, nil] Get guilds before this guild ID.
+  # @param after [String, nil] Get guilds after this guild ID.
+  # @param limit [Integer, nil] Maximum number of guilds to return. 1-200 allowed, 200 default.
+  # @param with_counts [TrueClass, FalseClass, nil] Whether to include approximate member and presence counts in
+  #   response.
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def get_current_user_guilds(before: nil, after: nil, limit: nil, with_counts: nil)
     query_string_hash = {}
     query_string_hash[:before] = before unless before.nil?
@@ -58,7 +74,7 @@ class DiscordApi
     url = "#{@base_url}/users/@me/guilds#{query_string}"
     headers = { 'Authorization': @authorization_header }
     response = DiscordApi.get(url, headers)
-    if @authorization_token_type == 'Bot' && response.body.count == 200
+    if response.status == 200 && @authorization_token_type == 'Bot' && JSON.parse(response.body).count == 200
       @logger.warn('A bot can be in more than 200 guilds, however 200 guilds were returned.' \
                     'Discord API doesn\'t allow you to fetch more than 200 guilds. Some guilds might not be listed.')
       return response
@@ -69,6 +85,26 @@ class DiscordApi
     response
   end
 
+  # Returns a guild member object for the current user in the specified guild.
+  # See https://discord.com/developers/docs/resources/user#get-current-user-guild-member
+  # @param guild_id [String] The ID of the guild to get the current user's guild member for.
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
+  def get_current_user_guild_member(guild_id)
+    url = "#{@base_url}/users/@me/guilds/#{guild_id}/member"
+    headers = { 'Authorization': @authorization_header }
+    response = DiscordApi.get(url, headers)
+    return response unless response.status != 200
+
+    @logger.error("Failed to get current user's guild member for guild ID with ID #{guild_id}. Response: " \
+                    "#{response.body}")
+    response
+  end
+
+  # Leaves a guild for the current user. If it succeeds, the response will have a status code of 204 (Empty Response),
+  # and thus the response body will be empty.
+  # See https://discord.com/developers/docs/resources/user#leave-guild
+  # @param guild_id [String] The ID of the guild to leave.
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def leave_guild(guild_id)
     url = "#{@base_url}/users/@me/guilds/#{guild_id}"
     headers = { 'Authorization': @authorization_header }
@@ -79,6 +115,11 @@ class DiscordApi
     response
   end
 
+  # Creates a DM channel with the specified user. Returns a DM channel object
+  # (if one already exists, it will return that channel).
+  # See https://discord.com/developers/docs/resources/user#create-dm
+  # @param recipient_id [String] The ID of the user to create a DM channel with.
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def create_dm(recipient_id)
     url = "#{@base_url}/users/@me/channels"
     data = JSON.generate({ recipient_id: recipient_id })
@@ -90,6 +131,12 @@ class DiscordApi
     response
   end
 
+  # Creates a group DM channel with the specified users. Returns a group DM channel object.
+  # See https://discord.com/developers/docs/resources/user#create-group-dm
+  # @param access_tokens [Array] An array of access tokens (as strings) of users that have granted your app the gdm.join
+  #   OAuth2 scope
+  # @param nicks [Hash] "a dictionary of user ids to their respective nicknames" (whatever that means)
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def create_group_dm(access_tokens, nicks)
     output = {}
     output[:access_tokens] = access_tokens
@@ -104,6 +151,9 @@ class DiscordApi
     response
   end
 
+  # Returns an array of connection objects for the current user. Requires the connections OAuth2 scope.
+  # See https://discord.com/developers/docs/resources/user#get-current-user-connections
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def get_current_user_connections
     url = "#{@base_url}/users/@me/connections"
     headers = { 'Authorization': @authorization_header }
@@ -114,6 +164,11 @@ class DiscordApi
     response
   end
 
+  # Returns the application role connection object for the user. Requires the role_connections.write OAuth2 scope for
+  # the application specified.
+  # See https://discord.com/developers/docs/resources/user#get-current-user-application-role-connection
+  # @param application_id [String] The ID of the application to get the role connection for.
+  # @return [Faraday::Response] The response from the Discord API as a Faraday::Response object.
   def get_current_user_application_role_connection(application_id)
     url = "#{@base_url}/users/@me/applications/#{application_id}/role-connection"
     headers = { 'Authorization': @authorization_header }
@@ -125,6 +180,18 @@ class DiscordApi
     response
   end
 
+  # Updates and returns the application role connection object for the user. Requires the role_connections.write OAuth2
+  # scope for the application specified.
+  # See https://discord.com/developers/docs/resources/user#update-current-user-application-role-connection
+  #
+  # If none of the optional parameters are provided (modifications), the function will not proceed and return nil.
+  # @param application_id [String] The ID of the application to update the role connection for.
+  # @param platform_name [String, nil] The vanity name of the platform a bot has connected (max 50 chars)
+  # @param platform_username [String, nil] The username on the platform a bot has connected (max 100 chars)
+  # @param metadata [Hash, nil] Hash mapping application role connection metadata keys to their string-ified values
+  #   (max 100 chars) for the user on the platform a bot has connected.
+  # @return [Faraday::Response, nil] The response from the Discord API as a Faraday::Response object or nil if no
+  #   modifications were provided.
   def update_current_user_application_role_connection(application_id, platform_name: nil, platform_username: nil,
                                                       metadata: nil)
     output = {}