Merge branch 'documentation' into 'main'

docs: create internal documentation

See merge request Erenoit/discord-bot!15

Author: Erenoit

src/bot/commands/entertainment/mod.rs

@@ -1,2 +1,4 @@
+//! Contains all the entertainment commands.
+
 pub mod meme;
 pub mod sus;

src/bot/commands/macros.rs

@@ -1,3 +1,11 @@
+/// Gives [`Server`] and [`Guild`] for the given [`Context`].
+///
+/// Most of the commands need these two, so this macro is used to reduce code
+/// repetition.
+///
+/// [`Server`]: crate::server::Server
+/// [`Guild`]: serenity::model::guild::Guild
+/// [`Context`]: crate::bot::commands::Context
 macro_rules! get_common {
     ($ctx:ident) => {{
         use std::sync::Arc;
@@ -9,6 +17,11 @@ macro_rules! get_common {
     }};
 }
 
+/// Gives [`PoolConnection<Sqlite>`] and sending `Discord` messages for errors.
+/// Needs [`bot::commands::Context`] to be able to send error messages.
+///
+/// [`PoolConnection<Sqlite>`]: sqlx::pool::PoolConnection
+/// [`Bot::commands::Context`]: crate::bot::commands::Context
 #[cfg(feature = "database")]
 macro_rules! db_connection {
     ($ctx: ident) => {{

src/bot/commands/mod.rs

@@ -1,3 +1,14 @@
+//! The module containing all the commands for the bot.
+//!
+//! The commands are split into categories, which are then split into their
+//! individual modules. This is done to make it easier to find commands and to
+//! make it easier to add new commands.
+//!
+//! The categories are:
+//! - Entertainment
+//! - Music
+//! - Others
+
 #[macro_use]
 mod macros;
 

src/bot/commands/music/mod.rs

@@ -1,3 +1,5 @@
+//! Contains all the music commands.
+
 pub mod clear;
 pub mod join;
 pub mod leave;

src/bot/commands/others/mod.rs

@@ -1,3 +1,5 @@
+//! Contains all the commands that don't fit in any other category.
+
 pub mod help;
 pub mod ping;
 pub mod register;

src/bot/event.rs

@@ -11,6 +11,9 @@ use serenity::{
 
 use crate::server::Server;
 
+/// Struct for handling `Discord` events.
+///
+/// It currently handles `Ready`, `GuildCreate` and `GuildDelete` events.
 pub struct Handler;
 impl Handler {
     pub const fn new() -> Self { Self }

src/bot/mod.rs

@@ -1,3 +1,11 @@
+//! Main module for the bot.
+//!
+//! This module contains the main struct for the bot, which is `Bot`. It also
+//! handles everything related to discord except music. For music see
+//! [`Player`].
+//!
+//! [`Player`]: crate::music::Player
+
 mod commands;
 mod event;
 
@@ -8,12 +16,17 @@ use songbird::SerenityInit;
 
 pub use crate::bot::commands::Context;
 
+/// The main struct for the bot.
+///
+/// Every interaction with `Discord` is done through this struct.
 #[non_exhaustive]
 pub struct Bot;
 
 impl Bot {
+    /// Creates a new instance of the bot.
     pub const fn new() -> Self { Self }
 
+    /// Runs the bot.
     pub async fn run(&mut self) {
         #[cfg(feature = "database")]
         get_config!()

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 }
 }