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

src/db/mod.rs

@@ -8,45 +8,74 @@ use tracing::error;
 
 pub type Result<T> = ::std::result::Result<T, sqlx::Error>;
 
-pub struct Database {
-    pool: SqlitePool,
-}
+pub struct Database(SqlitePool);
 
 impl Database {
+    /// Initialize Sqlite database.
+    ///
+    /// The Sqlite database should already exist and have its
+    /// migrations already executed.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the environment variable `DATABASE_URL` is not set.
+    ///
+    /// # Errors
+    ///
+    /// This function will return an error if the Sqlite pool fails to
+    /// create.
     pub async fn new() -> Result<Self> {
-        Ok(Self {
-            pool: SqlitePool::connect(
+        Ok(Self(
+            SqlitePool::connect(
                 &env::var("DATABASE_URL")
                     .expect("Missing enviroment variable DATABASE_URL"),
             )
             .await?,
-        })
+        ))
     }
 
+    /// Return from database all channels registered as loggers for a
+    /// guild.
+    ///
+    /// # Errors
+    ///
+    /// This function will return an error if `sqlx` does so.
     pub async fn get_logging_channels(
         &self,
         guild_id: GuildId,
-    ) -> Result<Vec<u64>> {
+    ) -> Result<Vec<ChannelId>> {
         let guild_id = guild_id.0 as i64;
-        let channels = sqlx::query!(
+        sqlx::query!(
             r#"
 SELECT channel_id
 FROM guild_log_channels
-WHERE guild_id = ?1
-            "#,
+WHERE guild_id = ?1"#,
             guild_id
         )
-        .fetch_all(&self.pool)
+        .fetch_all(&self.0)
         .await
         .map_err(|e| {
             error!(
                 "Error getting logging channels for guild {guild_id}: {e:?}"
             );
             e
-        })?;
-        Ok(channels.iter().map(|id| id.channel_id as u64).collect())
+        })
+        .map(|channels| {
+            channels
+                .iter()
+                .map(|id| ChannelId(id.channel_id as u64))
+                .collect()
+        })
     }
 
+    /// Adds a channel as a logger for a guild.
+    ///
+    /// # Errors
+    ///
+    /// This function will return an error if `sqlx` does so. This may
+    /// be either a database issue, or a channel is already registered
+    /// as a guild's logger, therefore violating the unicity
+    /// constraint for guild ID and channel ID pairs.
     pub async fn set_logging_channel(
         &self,
         guild_id: GuildId,
@@ -54,13 +83,11 @@ WHERE guild_id = ?1
     ) -> Result<()> {
         let guild_id = guild_id.0 as i64;
         let channel_id = channel_id.0 as i64;
-        let mut conn = self.pool.acquire().await?;
+        let mut conn = self.0.acquire().await?;
 
-        sqlx::query!(
-            r#"
+        sqlx::query!(r#"
 INSERT INTO guild_log_channels (guild_id, channel_id)
-VALUES ( ?1, ?2 )
-            "#,
+VALUES ( ?1, ?2 )"#,
             guild_id,
             channel_id
         )
@@ -73,18 +100,25 @@ VALUES ( ?1, ?2 )
         .map(|_| ())
     }
 
+    /// Unregister a channel as a logger for a guild.
+    ///
+    /// This function will return a success value even if `channel`
+    /// was not a logger of `guild` already.
+    ///
+    /// # Errors
+    ///
+    /// This function will return an error if `sqlx` does so.
     pub async fn remove_logging_channel(
         &self,
-        guild_id: GuildId,
-        channel_id: ChannelId,
+        guild: GuildId,
+        channel: ChannelId,
     ) -> Result<()> {
-        let guild_id = guild_id.0 as i64;
-        let channel_id = channel_id.0 as i64;
-        let mut conn = self.pool.acquire().await?;
+        let guild_id = guild.0 as i64;
+        let channel_id = channel.0 as i64;
+        let mut conn = self.0.acquire().await?;
         sqlx::query!(r#"
 DELETE FROM guild_log_channels
-WHERE guild_id = ?1 AND channel_id = ?2
-                     "#,
+WHERE guild_id = ?1 AND channel_id = ?2"#,
                      guild_id,
                      channel_id)
             .execute(&mut *conn)