Change inform! to user_error! and document them

Author: Urgau

src/handlers.rs

@@ -10,9 +10,15 @@ use std::fmt;
 use std::sync::Arc;
 use tracing as log;
 
-macro_rules! inform {
+/// Creates a [`UserError`] with message.
+///
+/// Should be used when an handler is in error due to the user action's (not a PR,
+/// not a issue, not authorized, ...).
+///
+/// Should be used like this `return user_error!("My error message.");`.
+macro_rules! user_error {
     ($err:expr $(,)?) => {
-        anyhow::bail!(crate::handlers::UserError($err.into()))
+        anyhow::Result::Err(anyhow::anyhow!(crate::handlers::UserError($err.into())))
     };
 }
 
@@ -439,6 +445,9 @@ impl fmt::Display for HandlerError {
     }
 }
 
+/// Represent a user error.
+///
+/// The message will be shown to the user via comment posted by this bot.
 #[derive(Debug)]
 pub struct UserError(String);
 

src/handlers/assign.rs

@@ -525,7 +525,7 @@ pub(super) async fn handle_command(
     let issue = event.issue().unwrap();
     if issue.is_pr() {
         if !issue.is_open() {
-            inform!("Assignment is not allowed on a closed PR.");
+            return user_error!("Assignment is not allowed on a closed PR.");
         }
         if matches!(
             event,
@@ -609,7 +609,7 @@ pub(super) async fn handle_command(
             AssignCommand::Claim => event.user().login.clone(),
             AssignCommand::AssignUser { username } => {
                 if !is_team_member && username != event.user().login {
-                    inform!("Only Rust team members can assign other users");
+                    return user_error!("Only Rust team members can assign other users");
                 }
                 username.clone()
             }
@@ -624,7 +624,7 @@ pub(super) async fn handle_command(
                         e.apply(&ctx.github, String::new()).await?;
                         return Ok(());
                     } else {
-                        inform!("Cannot release another user's assignment");
+                        return user_error!("Cannot release another user's assignment");
                     }
                 } else {
                     let current = &event.user().login;
@@ -636,11 +636,13 @@ pub(super) async fn handle_command(
                         e.apply(&ctx.github, String::new()).await?;
                         return Ok(());
                     } else {
-                        inform!("Cannot release unassigned issue");
+                        return user_error!("Cannot release unassigned issue");
                     }
                 };
             }
-            AssignCommand::RequestReview { .. } => inform!("r? is only allowed on PRs."),
+            AssignCommand::RequestReview { .. } => {
+                return user_error!("r? is only allowed on PRs.");
+            }
         };
         // Don't re-assign if aleady assigned, e.g. on comment edit
         if issue.contain_assignee(&to_assign) {

src/handlers/close.rs

@@ -16,7 +16,7 @@ pub(super) async fn handle_command(
         .await
         .unwrap_or(false);
     if !is_team_member {
-        inform!("Only team members can close issues.");
+        return user_error!("Only team members can close issues.");
     }
     issue.close(&ctx.github).await?;
     Ok(())

src/handlers/concern.rs

@@ -37,7 +37,7 @@ pub(super) async fn handle_command(
     cmd: ConcernCommand,
 ) -> anyhow::Result<()> {
     let Event::IssueComment(issue_comment) = event else {
-        inform!("Concerns can only be issued on an issue");
+        return user_error!("Concerns can only be issued on an issue");
     };
     let Some(comment_url) = event.html_url() else {
         bail!("unable to retrieve the comment url")
@@ -81,7 +81,7 @@ pub(super) async fn handle_command(
             issue.number,
             issue_comment.comment.user,
         );
-        inform!(
+        return user_error!(
             "Only team members in the [team repo](https://github.com/rust-lang/team) can add or resolve concerns."
         );
     }

src/handlers/major_change.rs

@@ -112,7 +112,7 @@ pub(super) async fn handle_input(
         .iter()
         .any(|l| l.name == config.enabling_label)
     {
-        inform!(format!(
+        return user_error!(format!(
             "This issue is not ready for proposals; it lacks the `{}` label.",
             config.enabling_label
         ));
@@ -247,7 +247,7 @@ pub(super) async fn handle_command(
         .iter()
         .any(|l| l.name == config.enabling_label)
     {
-        inform!(format!(
+        return user_error!(format!(
             "This issue cannot be seconded; it lacks the `{}` label.",
             config.enabling_label
         ));
@@ -261,7 +261,7 @@ pub(super) async fn handle_command(
         .unwrap_or(false);
 
     if !is_team_member {
-        inform!("Only team members can second issues.");
+        return user_error!("Only team members can second issues.");
     }
 
     let has_concerns = if let Some(concerns_label) = &config.concerns_label {

src/handlers/nominate.rs

@@ -21,7 +21,7 @@ pub(super) async fn handle_command(
     };
 
     if !is_team_member {
-        inform!(
+        return user_error!(
             "Nominating and approving issues and pull requests is restricted to members of the Rust teams."
         );
     }

src/handlers/ping.rs

@@ -24,13 +24,13 @@ pub(super) async fn handle_command(
     };
 
     if !is_team_member {
-        inform!("Only Rust team members can ping teams.");
+        return user_error!("Only Rust team members can ping teams.");
     }
 
     let (gh_team, config) = match config.get_by_name(&team_name.team) {
         Some(v) => v,
         None => {
-            inform!(format!(
+            return user_error!(format!(
                 "This team (`{}`) cannot be pinged via this command; \
                     it may need to be added to `triagebot.toml` on the default branch.",
                 team_name.team,
@@ -41,7 +41,7 @@ pub(super) async fn handle_command(
     let team = match team {
         Some(team) => team,
         None => {
-            inform!(format!(
+            return user_error!(format!(
                 "This team (`{}`) does not exist in the team repository.",
                 team_name.team,
             ));
@@ -60,7 +60,7 @@ pub(super) async fn handle_command(
             )
             .await
         {
-            inform!(format!("Error adding team label (`{}`): {:?}.", label, err));
+            return user_error!(format!("Error adding team label (`{}`): {:?}.", label, err));
         }
     }
 

src/handlers/relabel.rs

@@ -27,7 +27,7 @@ pub(super) async fn handle_command(
     input: RelabelCommand,
 ) -> anyhow::Result<()> {
     let Some(issue) = event.issue() else {
-        inform!("Can only add and remove labels on an issue");
+        return user_error!("Can only add and remove labels on an issue");
     };
 
     // Check label authorization for the current user
@@ -48,7 +48,7 @@ pub(super) async fn handle_command(
         };
         if let Some(err) = err {
             // bail-out and inform the user why
-            inform!(err);
+            return user_error!(err);
         }
     }
 

src/handlers/shortcut.rs

@@ -30,7 +30,7 @@ pub(super) async fn handle_command(
     let issue = event.issue().unwrap();
     // NOTE: if shortcuts available to issues are created, they need to be allowed here
     if !issue.is_pr() {
-        inform!(format!(
+        return user_error!(format!(
             "The \"{:?}\" shortcut only works on pull requests.",
             input
         ));