refactor: simplify code, better organize it, and comment it

src/discord/commands/logging.rs

@@ -1,7 +1,16 @@
-use super::{Context, Result};
+use super::super::{Context, Result};
 
-use super::utils::serenity;
+use poise::serenity_prelude as serenity;
 
+/// Main command for logging subcommands.
+///
+/// This command cannot be called on its own and will do nothing by
+/// itself.
+///
+/// # Errors
+///
+/// This command will never error out, even if its signature says it
+/// can.
 #[allow(clippy::unused_async)]
 #[poise::command(
     slash_command,
@@ -12,8 +21,13 @@ pub async fn logging(_ctx: Context<'_>) -> Result {
     Ok(())
 }
 
+/// Add a channel as a logger.
+///
+/// # Errors
+///
+/// This function will return an error if .
 #[poise::command(slash_command)]
-pub async fn add_channel(
+async fn add_channel(
     ctx: Context<'_>,
     #[description = "New logging channel"] channel: serenity::Channel,
 ) -> Result {
@@ -50,8 +64,16 @@ pub async fn add_channel(
     Ok(())
 }
 
+/// List all channels registered as loggers for a guild.
+///
+/// This will list all channels that are logger channels in the server
+/// from which the command was executed.
+///
+/// # Errors
+///
+/// This function will return an error if the database returns one.
 #[poise::command(slash_command)]
-pub async fn list_channels(ctx: Context<'_>) -> Result {
+async fn list_channels(ctx: Context<'_>) -> Result {
     let response = match ctx.guild_id() {
         None => "Error: Could not determine the guild's ID".to_owned(),
         Some(guild_id) => {
@@ -78,8 +100,18 @@ pub async fn list_channels(ctx: Context<'_>) -> Result {
     Ok(())
 }
 
+/// Remove a channel as a logger in a guild.
+///
+/// This will remove a channel from the list of logger channels in the
+/// guild from which the command was executed. If the channel is not a
+/// logger, the bot will still consider unsetting the channel as a
+/// logger a success.
+///
+/// # Errors
+///
+/// This function will return an error if the database errors.
 #[poise::command(slash_command)]
-pub async fn remove_channel(
+async fn remove_channel(
     ctx: Context<'_>,
     #[description = "Logger channel to remove"] channel: serenity::Channel,
 ) -> Result {

src/discord/commands/mod.rs

@@ -0,0 +1,3 @@
+mod logging;
+
+pub(crate) use logging::logging;

src/discord/error.rs

@@ -0,0 +1,24 @@
+use std::error::Error as StdError;
+use std::fmt::{self, Display};
+
+#[derive(Debug, Clone, Copy)]
+pub enum Error {
+    GuildIdNotFound,
+}
+
+impl Error {
+    pub fn boxed(self) -> Box<Self> {
+        Box::new(self)
+    }
+}
+
+impl Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+        // write!(f, "")
+        match self {
+            Self::GuildIdNotFound => write!(f, "Guild ID not found!"),
+        }
+    }
+}
+
+impl StdError for Error {}

src/discord/events.rs

@@ -1,72 +0,0 @@
-use crate::db::Database;
-
-use super::{utils::BotData, Error, Result};
-
-use poise::{serenity_prelude as serenity, Event};
-use tracing::{error, info};
-
-async fn handle_everyone_mention(
-    ctx: &serenity::Context,
-    database: &Database,
-    message: &serenity::Message,
-) -> Result {
-    use serenity::ChannelId;
-    if let Some(guild_id) = message.guild_id {
-        if message.mention_everyone {
-            let author = message.author.clone();
-            let message_channel = message.channel_id;
-            let channels: Vec<ChannelId> = database
-                .get_logging_channels(guild_id)
-                .await?
-                .iter()
-                .map(|channel_id| serenity::ChannelId(channel_id.to_owned()))
-                .collect();
-            for channel in &channels {
-                channel
-                    .send_message(&ctx, |m| {
-                        m.embed(|e| {
-                            e.title("Someone mentioned everyone!")
-                                .field("Author", author.clone(), true)
-                                .field(
-                                    "When",
-                                    message.timestamp.naive_local().to_string(),
-                                    true,
-                                )
-                                .field(
-                                    "Channel",
-                                    format!("<#{message_channel}>"),
-                                    true,
-                                )
-                                .field("Link", format!("https://discord.com/channels/{guild_id}/{}/{}", channel.0, message.id), false)
-                        })
-                    })
-                    .await
-                    .map_err(|e| {
-                        error!("Failed to send message: {e:?}");
-                        e
-                    })?;
-            }
-        }
-    } else {
-        error!("Could not determine guild id of message {message:?}");
-    }
-    Ok(())
-}
-
-pub async fn event_handler(
-    ctx: &serenity::Context,
-    event: &Event<'_>,
-    _framework: poise::FrameworkContext<'_, BotData, Error>,
-    data: &BotData,
-) -> Result {
-    match event {
-        Event::Ready { data_about_bot } => {
-            info!("Logged in as {}", data_about_bot.user.name);
-        }
-        Event::Message { new_message } => {
-            handle_everyone_mention(ctx, &data.database, new_message).await?;
-        }
-        _ => {}
-    }
-    Ok(())
-}

src/discord/events/everyone.rs

@@ -0,0 +1,68 @@
+use crate::db::Database;
+
+use super::super::Result;
+
+use super::super::error::Error as DiscordError;
+
+use poise::serenity_prelude::{self as serenity, CreateEmbed};
+use tracing::{error, info};
+
+fn message_for_everyone_mention(
+    embed: &mut CreateEmbed,
+    message: &serenity::Message,
+    guild_id: u64,
+) {
+    let author = message.author.clone();
+    let message_channel = message.channel_id.0;
+    embed
+        .title("Someone mentioned everyone!")
+        .field("Author", author.clone(), true)
+        .field("When", message.timestamp.naive_local().to_string(), true)
+        .field("Channel", format!("<#{message_channel}>"), true)
+        .field(
+            "Link",
+            format!(
+                "https://discord.com/channels/{guild_id}/{message_channel}/{}",
+                message.id
+            ),
+            false,
+        );
+}
+
+/// Handle messages mentioning everyone.
+///
+/// # Errors
+///
+/// This function will return an error if a message fails to be sent,
+/// if retrieving the list of channels registered as loggers fails, or
+/// if there is not guild ID that can be retrieved from the message.
+pub async fn handle_everyone_mention(
+    ctx: &serenity::Context,
+    database: &Database,
+    message: &serenity::Message,
+) -> Result {
+    info!("Message mentioning everyone: {message:?}");
+    if !message.mention_everyone {
+        return Ok(());
+    }
+    if message.guild_id.is_none() {
+        error!("Message without a guild_id! {message:?}");
+        return Err(DiscordError::GuildIdNotFound.boxed());
+    }
+    let guild_id = message.guild_id.unwrap();
+    let channels: Vec<serenity::ChannelId> =
+        database.get_logging_channels(guild_id).await?;
+    for channel in &channels {
+        // Ignore result, it'll be in the bot's logger
+        let _ = channel
+            .send_message(&ctx, |m| {
+                m.embed(|e| {
+                    message_for_everyone_mention(e, message, guild_id.0);
+                    e
+                })
+            })
+            .await
+            .map_err(|e| error!("Failed to send message: {e:?}"));
+    }
+    Ok(())
+}

src/discord/events/mod.rs

@@ -0,0 +1,34 @@
+use super::{utils::BotData, Error, Result};
+
+use poise::{
+    serenity_prelude::{self as serenity},
+    Event,
+};
+use tracing::info;
+
+mod everyone;
+use everyone::handle_everyone_mention;
+
+/// Function handling events the bot can see.
+///
+/// # Errors
+///
+/// This function will return an error if one of the functions error
+/// themselves.
+pub async fn event_handler(
+    ctx: &serenity::Context,
+    event: &Event<'_>,
+    _framework: poise::FrameworkContext<'_, BotData, Error>,
+    data: &BotData,
+) -> Result {
+    match event {
+        Event::Ready { data_about_bot } => {
+            info!("Logged in as {}", data_about_bot.user.name);
+        }
+        Event::Message { new_message } => {
+            handle_everyone_mention(ctx, &data.database, new_message).await?;
+        }
+        _ => {}
+    }
+    Ok(())
+}

src/discord/mod.rs

@@ -1,6 +1,7 @@
 mod commands;
 mod events;
 pub mod utils;
+pub mod error;
 
 use poise::FrameworkBuilder;
 use utils::serenity;
@@ -12,6 +13,11 @@ use self::events::event_handler;
 
 pub type Result = ::std::result::Result<(), Error>;
 
+/// Bootstraps the Discord bot.
+///
+/// # Panics
+///
+/// Panics if the environment `DISCORD_TOKEN` is unavailable.
 pub fn make_bot() -> FrameworkBuilder<BotData, Error> {
     poise::Framework::builder()
         .options(poise::FrameworkOptions {

src/discord/utils.rs

@@ -6,6 +6,14 @@ pub struct BotData {
 }
 
 impl BotData {
+    /// Initialize state data for bot.
+    ///
+    /// For now, this only includes a connector to its database.
+    ///
+    /// # Errors
+    ///
+    /// This function will return an error if the database fails to
+    /// initialize.
     pub async fn new() -> color_eyre::Result<Self> {
         Ok(Self {
             database: Database::new().await?,