doc: add commands doc

Cargo.toml

@@ -7,7 +7,7 @@ edition = "2024"
 anyhow = "1.0.100"
 chrono = "0.4.42"
 config = { version = "0.15.19", default-features = false }
-poise = "0.6.1"
+poise = { git = "https://github.com/serenity-rs/poise" }
 regex = "1.12.2"
 serde = { version = "1.0.228", features = ["derive"] }
 sqlx = { version = "0.8.6", features = ["chrono", "runtime-tokio", "sqlite"] }

src/command/add.rs

@@ -3,9 +3,13 @@ use poise::serenity_prelude as serenity;
 
 use crate::{Context, Message, database, util};
 
+/// Add one or more candidate IDs to the candidates database from a text file.
 #[tracing::instrument]
 #[poise::command(slash_command, prefix_command, ephemeral)]
-pub async fn add(ctx: Context<'_>, id: serenity::Attachment) -> Result<()> {
+pub async fn add(
+    ctx: Context<'_>,
+    #[description = "Text file with candidate IDs (one per line, UTF‑8)"] id: serenity::Attachment,
+) -> Result<()> {
     let pool = &ctx.data().pool;
 
     let id = id.download().await?;

src/command/delete.rs

@@ -2,9 +2,13 @@ use anyhow::Result;
 
 use crate::{Context, Message, database, util};
 
+/// Delete a candidate by ID from the candidates database.
 #[tracing::instrument]
 #[poise::command(slash_command, prefix_command, ephemeral)]
-pub async fn delete(ctx: Context<'_>, id: String) -> Result<()> {
+pub async fn delete(
+    ctx: Context<'_>,
+    #[description = "Candidate ID to delete"] id: String,
+) -> Result<()> {
     let pool = &ctx.data().pool;
 
     if !util::is_valid_id(&id) {

src/command/help.rs

@@ -1,13 +1,13 @@
 use anyhow::Result;
-use poise::builtins::HelpConfiguration;
+use poise::builtins::PrettyHelpConfiguration;
 
 use crate::Context;
 
 #[tracing::instrument]
 #[poise::command(slash_command, prefix_command, ephemeral)]
 pub async fn help(ctx: Context<'_>, command: Option<String>) -> Result<()> {
-    let configuration = HelpConfiguration::default();
-    poise::builtins::help(ctx, command.as_deref(), configuration).await?;
+    let configuration = PrettyHelpConfiguration::default();
+    poise::builtins::pretty_help(ctx, command.as_deref(), configuration).await?;
 
     Ok(())
 }

src/command/ping.rs

@@ -2,6 +2,7 @@ use anyhow::Result;
 
 use crate::Context;
 
+/// Test if bot is responsive
 #[tracing::instrument]
 #[poise::command(slash_command, prefix_command, ephemeral)]
 pub async fn ping(ctx: Context<'_>) -> Result<()> {

src/command/verify.rs

@@ -5,6 +5,7 @@ use crate::{Context, Message, database, util};
 
 const ROLE: &str = "Round 1: Challenger";
 
+/// Verify a candidate and assign role upon success.
 #[tracing::instrument]
 #[poise::command(slash_command, prefix_command, ephemeral)]
 pub async fn verify(ctx: Context<'_>, id: String) -> Result<()> {