From 6ca2649840cc48ba479e39a682605cddd0c47563 Mon Sep 17 00:00:00 2001 From: Rafael Bradley Date: Sun, 10 Aug 2025 21:52:14 -0300 Subject: [PATCH] Add docs for the CLI module --- src/cli.rs | 46 +++++++++++++++++++++++++++++++++++++++++++--- src/main.rs | 50 +++++++++++++++++++++++++------------------------- 2 files changed, 68 insertions(+), 28 deletions(-) diff --git a/src/cli.rs b/src/cli.rs index d5ff5c2..6d5f6d4 100644 --- a/src/cli.rs +++ b/src/cli.rs @@ -1,3 +1,43 @@ +//! Payphone's main entry point, which initializes the bot and starts the event loop. +//! +//! This module is responsible for parsing command line arguments, nothing else. +//! +//! # Command Line Arguments +//! +//! The command line arguments are parsed using the [`clap`] crate, and can be found in the +//! [`Args`] struct. The arguments are: +//! +//! - `--token` or `-t`: The Discord bot token to run the bot with. This is required. +//! - `--logging` or `-l`: The minimum level logs have to be to be outputted into the console, or +//! off for no logs. Defaults to `info`. +//! - `--database-addr` or `-d`: The address of the database to connect to, a Scylla node. +//! +//! The CLI also supports setting argument values via environment variables. The environment +//! variables are prefixed with `PAYPHONE_`, so for example, the `--token` argument can be set +//! using the `PAYPHONE_TOKEN` environment variable. The environment variables are used to +//! override the command line arguments. `.env` files are also supported by default, so you can +//! create a `.env` file in the root of the project with the following content: +//! +//! ```env +//! PAYPHONE_TOKEN="your_discord_bot_token" +//! PAYPHONE_LOGGING="info" +//! PAYPHONE_DATABASE_ADDR="your_database_addr" +//! ``` +//! +//! # Parsing Arguments +//! +//! The arguments are parsed using the [`Args::parse`] method, which returns an instance of the +//! [`Args`] struct. This struct contains the parsed values of the command line arguments, and +//! can be used to initialize the bot and start the event loop. +//! +//! ``` +//! // Read the environment variables from the `.env` file, if it exists, and load them as proper +//! // env variables. +//! dotenvy::dotenv().ok(); +//! +//! let args = Args::parse(); +//! ``` + #[derive(clap::Parser)] pub struct Args { /// The Discord bot token to run the bot with. @@ -18,11 +58,11 @@ pub struct Args { #[arg( long, short, - env = "PAYPHONE_DATABASE_URL", - value_name = "URL", + env = "PAYPHONE_DATABASE_ADDR", + value_name = "ADDR", default_value_t = String::from("127.0.0.1:9042")) ] - pub database_url: String, + pub database_addr: String, } #[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, clap::ValueEnum)] diff --git a/src/main.rs b/src/main.rs index 9c88a82..01ee9fc 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,78 +1,78 @@ //! Payphone is a Discord bot that allows users to make calls to each other, similar to a phone //! system. -//! +//! //! # Setting Up -//! +//! //! First of all, clone the Git repository and navigate to the project directory: -//! +//! //! ```shell //! $ git clone --branch rewrite https://git.nyeki.dev/payphone/payphone.git //! $ cd payphone //! ``` -//! +//! //! To boot up Payphone, you'll need both a Discord bot token and a Scylla database cluster with //! at least 3 nodes. -//! +//! //! - To get a Discord bot token, create a new bot application on the //! [Discord Developer Portal](https://discord.com/developers/applications). -//! +//! //! - To set up a Scylla database cluster, make sure to have Docker and Docker Compose installed //! and run `docker compose up -d`. A development cluster will be created with 3 nodes, with one //! of them listening at `127.0.0.1:9042`. -//! +//! //! To stop the database cluster at any time, run `docker compose down`. To stop it and delete the //! volumes (resetting the database), run `docker compose down -v`. -//! +//! //! ## Booting Up -//! +//! //! Payphone has a CLI interface that allows you to pass the bot token and database URL as CLI //! arguments. To get all possible arguments, run the following command: -//! +//! //! ```shell //! $ cargo run -- --help //! ``` -//! +//! //! Payphone also supports configuration via environment variables and `.env` files by default. -//! +//! //! ```env //! PAYPHONE_TOKEN="your_discord_bot_token" //! ``` -//! +//! //! All environment variables are prefixed with `PAYPHONE_` and can be used to override the CLI //! arguments. -//! +//! //! # Framework -//! +//! //! Payphone has a custom framework that allows you to create commands, components, and event //! handlers easily. The framework is designed to be modular and extensible, allowing you to add //! new features and commands without modifying the core codebase. The documentation for the //! framework is all in the [`framework`] module. -//! +//! //! # Database -//! +//! //! The database Payphone runs on is ScyllaDB, a high-performance NoSQL database compatible with -//! Apache Cassandra. For documentation on how to interact with the database, check the +//! Apache Cassandra. For documentation on how to interact with the database, check the //! [`database`] module's documentation. -//! +//! //! # Application Code -//! +//! //! Payphone's application code is under the [`groups`] module. It contains all commands, events, //! embeds, and other configurations for the bot grouped in submodules (e.g. [`groups::calls`], //! [`groups::about`], etc.), all which can be found at the [`groups`] module's documentation. -//! +//! //! Each submodule contains files like `commands.rs`, `events.rs`, `embeds.rs`, and `components.rs` //! that define the commands, events, embeds, and components for that group. Some common file names //! are: -//! +//! //! - `commands.rs`: Contains the commands for the group. //! - `events.rs`: Contains the event handlers for the group. //! - `embeds.rs`: Contains the embeds for the group. //! - `components.rs`: Contains the components for the group (action rows, buttons, soon also //! select menus). -//! +//! //! Always try to follow the same structure and patterns as the existing code to maintain //! consistency and readability. -//! +//! //! More documentation about each group can be found in the respective submodule's documentation. use clap::Parser; @@ -117,7 +117,7 @@ pub async fn main() { env!("CARGO_PKG_VERSION") ); - let db = database::init(args.database_url) + let db = database::init(args.database_addr) .await .expect("Could not connect to the database!");