Add more documentation

src/framework/runtime.rs

@@ -1,3 +1,22 @@
+//! Runtime app state of the shard.
+//!
+//! The [`Runtime`] is an abstraction over the application's state and provides access to various
+//! components, such as the HTTP client, application information, and command registry. This was
+//! done because there's a lot of data the application depends on to execute, and passing all those
+//! values around individually was cumbersome.
+//!
+//! The [`Runtime`] includes the following data:
+//!
+//! - The HTTP API client.
+//! - The application's details, including the user profile.
+//! - The component registry.
+//! - The prefix getter.
+//! - The list of available commands.
+//! - The app state.
+//!
+//! The [`Runtime`] is always passed around as [`Arc<Runtime>`], so it can be easily shared between
+//! different parts of the application.
+
 use std::sync::Arc;
 
 use twilight_http::Client;
@@ -7,20 +26,51 @@ use crate::framework::{
     bot::IntoPrefixes, commands::Command, interactions::registry::ComponentRegistry,
 };
 
+/// The application's runtime tools.
 pub struct Runtime<T> {
+    /// The HTTP client used for making requests to the HTTP API.
     pub http: Client,
+
+    /// Details about the application.
     pub app: Application,
+
+    /// The component registry.
     pub registry: ComponentRegistry<T>,
+
+    /// The command prefixes getter.
     pub prefixes: Arc<dyn IntoPrefixes<T> + Send + Sync + 'static>,
+
+    /// The commands available in the application.
     pub commands: Vec<Arc<dyn Command<T>>>,
+
+    /// The application state.
     pub state: Arc<T>,
 }
 
 impl<T> Runtime<T> {
+    /// Get the command prefixes set for the server and user ID.
+    ///
+    /// Arguments:
+    /// * `server_id` - The ID of the server in which the command, interaction, or event is
+    ///   running. When this is [`None`] it means the prefix should be returned for the user's DM
+    ///   channel.
+    /// * `user_id` - The user who triggered the event.
+    ///
+    /// Returns:
+    /// [`Vec<String>`] - A list of prefixes, all which should be taken into account. It's safe to
+    /// default to the first item of the list when a single prefix should be used (e.g. to display
+    /// it to the user).
     pub async fn get_prefixes(&self, server_id: Option<u64>, user_id: Option<u64>) -> Vec<String> {
         self.prefixes.clone().get(self, server_id, user_id).await
     }
 
+    /// Get a command by its name or alias.
+    ///
+    /// Arguments:
+    /// * `name` - The command's name or alias, without prefix.
+    ///
+    /// Returns:
+    /// [`Option<Arc<dyn Command<T>>>`] - The command if found, otherwise `None`.
     pub fn get_command(&self, name: &str) -> Option<Arc<dyn Command<T>>> {
         self.commands
             .iter()

src/groups/calls/mod.rs

@@ -1,3 +1,5 @@
+//! Call commands and events.
+
 pub mod commands;
 pub mod events;
 pub(super) mod moderation;

src/groups/gateway/events.rs

@@ -1,3 +1,5 @@
+//! Event handling for the gateway sub-module.
+
 use std::sync::Arc;
 
 use async_trait::async_trait;
@@ -11,6 +13,7 @@ use crate::{
     state::State,
 };
 
+/// Logs a ready message when the bot is ready.
 #[derive(Debug)]
 pub struct ReadyHandler;
 
@@ -27,6 +30,7 @@ impl OnReadyHandler<State> for ReadyHandler {
     }
 }
 
+/// Logs a reconnection message when the gateway asks for a reconnection.
 #[derive(Debug)]
 pub struct ReconnectHandler;
 

src/groups/gateway/mod.rs

@@ -1 +1,3 @@
+//! Logging gateway events.
+
 pub mod events;

src/groups/servers/mod.rs

@@ -1,4 +1,4 @@
-//! Payphone's Discord server-related features.
+//! Adding, updating, and removing servers from the database.
 //!
 //! This sub-module is responsible for registering servers in the database, updating them when they
 //! update, and removing them when they get deleted or Payphone is kicked.