From a14ae96a4731b7d4f9b98a1b3f9f483c2ac70f25 Mon Sep 17 00:00:00 2001
From: Rafael Bradley <rafabradleyrb@gmail.com>
Date: Wed, 13 Aug 2025 14:48:47 -0300
Subject: [PATCH] Add more documentation

---
 src/framework/runtime.rs     | 50 ++++++++++++++++++++++++++++++++++++
 src/groups/calls/mod.rs      |  2 ++
 src/groups/gateway/events.rs |  4 +++
 src/groups/gateway/mod.rs    |  2 ++
 src/groups/servers/mod.rs    |  2 +-
 5 files changed, 59 insertions(+), 1 deletion(-)

diff --git a/src/framework/runtime.rs b/src/framework/runtime.rs
index 0571d12..9416eeb 100644
--- a/src/framework/runtime.rs
+++ b/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()
diff --git a/src/groups/calls/mod.rs b/src/groups/calls/mod.rs
index b9c70cd..21e492f 100644
--- a/src/groups/calls/mod.rs
+++ b/src/groups/calls/mod.rs
@@ -1,3 +1,5 @@
+//! Call commands and events.
+
 pub mod commands;
 pub mod events;
 pub(super) mod moderation;
diff --git a/src/groups/gateway/events.rs b/src/groups/gateway/events.rs
index 462b25e..c94db5f 100644
--- a/src/groups/gateway/events.rs
+++ b/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;
 
diff --git a/src/groups/gateway/mod.rs b/src/groups/gateway/mod.rs
index a9970c2..1d28ddd 100644
--- a/src/groups/gateway/mod.rs
+++ b/src/groups/gateway/mod.rs
@@ -1 +1,3 @@
+//! Logging gateway events.
+
 pub mod events;
diff --git a/src/groups/servers/mod.rs b/src/groups/servers/mod.rs
index bcdab60..a7e3886 100644
--- a/src/groups/servers/mod.rs
+++ b/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.