docs: add documentation for config module

Author: Erenoit

src/config/database.rs

@@ -1,3 +1,5 @@
+//! Database Configuration
+
 use std::{fs, path::PathBuf};
 
 use anyhow::{anyhow, Result};
@@ -10,11 +12,14 @@ use crate::config::Node;
 
 #[non_exhaustive]
 pub(super) struct DatabaseConfig {
+    /// Database pool.
     pool: SqlitePool,
+    /// Database URL/location.
     url:  String,
 }
 
 impl DatabaseConfig {
+    /// Generate a new `DatabaseConfig` from the config file.
     pub fn generate(config_file: &Node, default_path: PathBuf) -> Result<Self> {
         // TODO: make cmd argument priority over config file one
         let path = get_value!(config_file, PathBuf, "BOT_DATABASE_LOCATION", "database"=>"location", default_path)?;
@@ -38,12 +43,15 @@ impl DatabaseConfig {
         Ok(Self { pool, url })
     }
 
+    /// Run database migrations.
     pub async fn run_migrations(&self) -> Result<()> {
         sqlx::migrate!().run(&self.pool).await?;
         Ok(())
     }
 
+    /// Returns the database pool.
     pub const fn pool(&self) -> &SqlitePool { &self.pool }
 
+    /// Returns the database URL.
     pub const fn url(&self) -> &String { &self.url }
 }

src/config/defaults.rs

@@ -1,3 +1,9 @@
+//! Default values for the config.
+//!
+//! This file contains the default values for the config. These values are used
+//! when the config file is not present or when a value is missing from the
+//! config file.
+
 pub(super) const PREFIX: &str = "-";
 pub(super) const AUTO_REGISTER_COMMANDS: bool = true;
 #[cfg(feature = "music")]

src/config/general.rs

@@ -1,3 +1,5 @@
+//! General Configuration
+
 use anyhow::Result;
 #[cfg(feature = "config_file")]
 use taplo::dom::Node;
@@ -10,14 +12,20 @@ use crate::config::Node;
 
 #[non_exhaustive]
 pub(super) struct GeneralConfig {
+    /// Discord token.
     token:                  String,
+    /// Prefix for commands.
     prefix:                 String,
+    /// Whether to auto register commands.
     auto_register_commands: bool,
+    /// Whether to auto change voice channel when user sended the command from
+    /// another voice cahnnel.
     #[cfg(feature = "music")]
     vc_auto_change:         bool,
 }
 
 impl GeneralConfig {
+    /// Generate a new `GeneralConfig` from the config file.
     pub fn generate(config_file: &Node) -> Result<Self> {
         let token = get_value!(config_file, String, "BOT_TOKEN", "general"=>"token", "Discord token couldn't found.")?;
         let prefix = get_value!(config_file, String, "BOT_PREFIX", "general"=>"prefix", PREFIX)?;
@@ -34,12 +42,17 @@ impl GeneralConfig {
         })
     }
 
+    /// Returns the Discord token.
     pub const fn token(&self) -> &String { &self.token }
 
+    /// Returns the prefix for commands.
     pub const fn prefix(&self) -> &String { &self.prefix }
 
+    /// Returns whether to auto register commands.
     pub const fn auto_register_commands(&self) -> bool { self.auto_register_commands }
 
+    /// Returns whether to auto change voice channel when user sended the
+    /// command from another voice cahnnel.
     #[cfg(feature = "music")]
     pub const fn vc_auto_change(&self) -> bool { self.vc_auto_change }
 }

src/config/message.rs

@@ -1,3 +1,5 @@
+//! Message Configuration.
+
 use anyhow::Result;
 #[cfg(feature = "config_file")]
 use taplo::dom::Node;
@@ -15,15 +17,22 @@ use crate::config::Node;
 
 #[non_exhaustive]
 pub(super) struct MessageConfig {
+    /// Whether to always use embed messages.
     always_embed:           bool,
+    /// Whether to use random colors for embed messages.
     random_embed_colors:    bool,
+    /// Color to use in embed message when the given command successes.
     success_color:          u32,
+    /// Color to use in embed message when there is no success/error.
     normal_color:           u32,
+    /// Color to use in embed message when the given command errors.
     error_color:            u32,
+    /// Time limit for interaction messages.
     interaction_time_limit: u64,
 }
 
 impl MessageConfig {
+    /// Generate a new `MessageConfig` from the config file.
     pub fn generate(config_file: &Node) -> Result<Self> {
         let always_embed = get_value!(config_file, bool, "BOT_MSG_ALWAYS_EMBED", "message"=>"always_embed", ALWAYS_EMBED)?;
         let random_embed_colors = get_value!(config_file, bool, "BOT_MSG_RANDOM_EMBED_COLORS", "message"=>"random_embed_colors", RANDOM_EMBED_COLORS)?;
@@ -42,15 +51,23 @@ impl MessageConfig {
         })
     }
 
+    /// Returns whether to always use embed messages.
     pub const fn always_embed(&self) -> bool { self.always_embed }
 
+    /// Returns whether to use random colors for embed messages.
     pub const fn random_embed_colors(&self) -> bool { self.random_embed_colors }
 
+    /// Returns the color to use in embed message when the given command
+    /// successes.
     pub const fn success_color(&self) -> u32 { self.success_color }
 
+    /// Returns the color to use in embed message when there is no
+    /// success/error.
     pub const fn normal_color(&self) -> u32 { self.normal_color }
 
+    /// Returns the color to use in embed message when the given command errors.
     pub const fn error_color(&self) -> u32 { self.error_color }
 
+    /// Returns the time limit for interaction messages.
     pub const fn interaction_time_limit(&self) -> u64 { self.interaction_time_limit }
 }

src/config/mod.rs

@@ -1,3 +1,24 @@
+//! This module keeps state of the bot
+//!
+//! Even though it started as storing configuration about bot, now it is
+//! responsible to store everything from configuration to music player state and
+//! probably the most confusing file/module in this project yet it is
+//! surprisingly straightforward.
+//!
+//! Main [`Config`] struct is divided into substructs/submodules. Each submodule
+//! is responsible for storing configuration about a specific part of the bot.
+//! Every struct is its own file to make it easier to find them.
+//!
+//! Also to not make every struct public their functions are re-exported in the
+//! main [`Config`] struct.
+//!
+//! ## Why constructer is named `generate()`?
+//! Every struct in config module and its submodules use `generate()` function
+//! to generate their struct. This is because this structs only created once and
+//! third party resources such as config files and environmental variables used
+//! in their creation. Using different name for the constructor other than
+//! `new()` is to make it clear that it is not a normal constructor.
+
 #[cfg(feature = "cmd")]
 mod cmd_arguments;
 mod defaults;
@@ -47,9 +68,13 @@ use crate::{
     server::Server,
 };
 
+/// Dummy type to use when `config_file` feature is not enabled. When
+/// `config_file` feature is disabled, [`taplo`] crate is disabled. therefore,
+/// there is no Node type, and this creates a compilation error.
 #[cfg(not(feature = "config_file"))]
 struct Node;
 
+/// Main struct to store everything
 #[non_exhaustive]
 pub struct Config {
     general:  GeneralConfig,
@@ -66,6 +91,7 @@ pub struct Config {
 }
 
 impl Config {
+    /// Generate [`Config`] from config sources
     pub fn generate() -> Result<Self> {
         #[cfg(feature = "cmd")]
         let cmd_arguments = CMDArguments::parse();
@@ -172,48 +198,95 @@ impl Config {
         })
     }
 
+    /// Get `Discord` token for bot
     pub const fn token(&self) -> &String { self.general.token() }
 
+    /// Get prefix for `prefix commands`
     pub const fn prefix(&self) -> &String { self.general.prefix() }
 
+    /// Register `slash commands` to `Discord`
     pub const fn auto_register_commands(&self) -> bool { self.general.auto_register_commands() }
 
+    /// Get `vc_auto_change` setting
     #[cfg(feature = "music")]
     pub const fn vc_auto_change(&self) -> bool { self.general.vc_auto_change() }
 
+    /// Get `message_always_embed` setting
+    ///
+    /// WARNING: You do not need to use this setting. [`message!()`] macro
+    /// already obeys this setting.
+    ///
+    /// [`message!()`]: crate::messager::message!()
     pub const fn message_always_embed(&self) -> bool { self.message.always_embed() }
 
+    /// Get `message_randowm_colors` setting
+    ///
+    /// WARNING: You do not need to use this setting. [`message!()`] macro
+    /// already obeys this setting.
+    ///
+    /// [`message!()`]: crate::messager::message!()
     pub const fn message_random_embed_colors(&self) -> bool { self.message.random_embed_colors() }
 
+    /// Get `message_success_color` setting
+    ///
+    /// WARNING: You do not need to use this setting. [`message!()`] macro
+    /// already obeys this setting.
+    ///
+    /// [`message!()`]: crate::messager::message!()
     pub const fn message_success_color(&self) -> u32 { self.message.success_color() }
 
+    /// Get `message_normal_color` setting
+    ///
+    /// WARNING: You do not need to use this setting. [`message!()`] macro
+    /// already obeys this setting.
+    ///
+    /// [`message!()`]: crate::messager::message!()
     pub const fn message_normal_color(&self) -> u32 { self.message.normal_color() }
 
+    /// Get `message_error_color` setting
+    ///
+    /// WARNING: You do not need to use this setting. [`message!()`] macro
+    /// already obeys this setting.
+    ///
+    /// [`message!()`]: crate::messager::message!()
     pub const fn message_error_color(&self) -> u32 { self.message.error_color() }
 
+    /// Get `message_interaction_time_limit` setting
     pub const fn message_interaction_time_limit(&self) -> u64 {
         self.message.interaction_time_limit()
     }
 
+    /// Get `youtube_search_count` setting
     #[cfg(feature = "music")]
     pub const fn youtube_search_count(&self) -> u8 { self.youtube.search_count() }
 
+    /// Get `youtube_age_resricted` setting
     #[cfg(feature = "music")]
     pub const fn youtube_age_restricted(&self) -> bool { self.youtube.age_restricted() }
 
+    /// Chack if `Spotify` enabled
     #[cfg(feature = "spotify")]
     pub const fn is_spotify_initialized(&self) -> bool { self.spotify.is_some() }
 
+    /// Get `Spotify` client credentials
     #[cfg(feature = "spotify")]
     pub fn spotify_client(&self) -> Option<(&String, &String)> {
         Some(self.spotify.as_ref()?.client())
     }
 
+    /// Get `Spotify` token
     #[cfg(feature = "spotify")]
     pub async fn spotify_token(&self) -> Option<String> {
         Some(self.spotify.as_ref()?.token().await)
     }
 
+    /// Get databse pool to interact with database
+    ///
+    /// WARNING: use [`bot::commands::macros::db_connection!()`] instead of this
+    /// if you want database connection in [bot command].
+    ///
+    /// [`bot::commands::macros::db_connection!()`]: crate::bot::commands::macros::db_connection!()
+    /// [bot_command]: crate::bot::commands
     #[cfg(feature = "database")]
     pub const fn database_pool(&self) -> Option<&SqlitePool> {
         if let Some(db) = &self.database {
@@ -223,6 +296,7 @@ impl Config {
         }
     }
 
+    /// Get database URL
     #[cfg(feature = "database")]
     pub const fn database_url(&self) -> Option<&String> {
         if let Some(db) = &self.database {
@@ -232,6 +306,7 @@ impl Config {
         }
     }
 
+    /// Run database migrations to setup database
     #[cfg(feature = "database")]
     pub async fn run_database_migrations(&self) -> Result<()> {
         if let Some(db) = &self.database {
@@ -241,8 +316,10 @@ impl Config {
         Ok(())
     }
 
+    /// Get connected servers
     pub const fn servers(&self) -> &RwLock<HashMap<GuildId, Arc<Server>>> { &self.servers }
 
+    /// Get main [`Songbird`] strcut
     #[cfg(feature = "music")]
     pub fn songbird(&self) -> Arc<Songbird> { Arc::clone(&self.songbird) }
 }

src/config/spotify.rs

@@ -1,3 +1,5 @@
+//! `Spotify` Configuration.
+
 use std::time::Instant;
 
 use anyhow::Result;
@@ -10,15 +12,20 @@ use crate::config::Node;
 
 #[non_exhaustive]
 pub(super) struct SpotifyConfig {
+    /// Client ID for Spotify API.
     client_id:     String,
+    /// Client secret for Spotify API.
     client_secret: String,
+    /// Token for Spotify API.
     token:         RwLock<Option<String>>,
+    /// Last time token was refreshed.
     last_refresh:  RwLock<Option<Instant>>,
 }
 
 impl SpotifyConfig {
     const REFRESH_TIME: u64 = 3500;
 
+    /// Generate a new `SpotifyConfig` from the config file.
     pub fn generate(config_file: &Node) -> Result<Self> {
         let client_id = get_value!(config_file, String, "BOT_SP_CLIENT_ID", "spotify"=>"client_id",
                                    "For Spotify support client ID is requared. Either set your client ID on the config file or disable Spotify support")?;
@@ -35,8 +42,11 @@ impl SpotifyConfig {
         })
     }
 
+    /// Returns the client ID and client secret.
     pub const fn client(&self) -> (&String, &String) { (&self.client_id, &self.client_secret) }
 
+    /// Returns the current token if it is not expired, otherwise it requests a
+    /// new one and return that.
     pub async fn token(&self) -> String {
         if self.token.read().await.is_none()
             || self
@@ -60,6 +70,7 @@ impl SpotifyConfig {
             .to_string()
     }
 
+    /// Request a new token from Spotify API.
     #[allow(clippy::significant_drop_tightening)]
     async fn refresh_token(&self) {
         let mut write_lock_token = self.token.write().await;

src/config/youtube.rs

@@ -1,3 +1,5 @@
+//! `YouTube` Configuration.
+
 use anyhow::Result;
 #[cfg(feature = "config_file")]
 use taplo::dom::Node;
@@ -10,19 +12,24 @@ use crate::config::Node;
 // TODO: implement this configs
 #[non_exhaustive]
 pub(super) struct YouTubeConfig {
+    /// Number of results to show when searching for a song.
     search_count:   u8,
+    /// Whether to allow age restricted videos.
     age_restricted: bool,
 }
 
 impl YouTubeConfig {
+    /// Generate a new `YouTubeConfig` from the config file.
     pub fn generate(config_file: &Node) -> Result<Self> {
         let search_count = get_value!(config_file, u8, "BOT_YT_SEARCH_COUNT", "youtube"=>"search_count", YT_SEARCH_COUNT)?;
         let age_restricted = get_value!(config_file, bool, "BOT_YT_AGE_RESTRICTED", "youtube"=>"age_restricted", YT_AGE_RESTRICTED)?;
 
         Ok(Self { search_count, age_restricted })
     }
 
+    /// Returns the number of results to show when searching for a song.
     pub const fn search_count(&self) -> u8 { self.search_count }
 
+    /// Returns whether to allow age restricted videos.
     pub const fn age_restricted(&self) -> bool { self.age_restricted }
 }