From a8a987df8eee449a69c6ca3544347c2c2f3697e5 Mon Sep 17 00:00:00 2001
From: Florian <me@fgardt.dev>
Date: Fri, 31 May 2024 04:53:07 +0200
Subject: [PATCH] Docs & example

---
 examples/feature_showcase/main.rs      | 13 ++++++
 examples/feature_showcase/user_apps.rs | 60 ++++++++++++++++++++++++++
 macros/src/lib.rs                      |  2 +
 3 files changed, 75 insertions(+)
 create mode 100644 examples/feature_showcase/user_apps.rs

diff --git a/examples/feature_showcase/main.rs b/examples/feature_showcase/main.rs
index 20c5b3c110c2..0725ad25b4b2 100644
--- a/examples/feature_showcase/main.rs
+++ b/examples/feature_showcase/main.rs
@@ -19,6 +19,9 @@ mod subcommand_required;
 mod subcommands;
 mod track_edits;
 
+#[cfg(feature = "unstable")]
+mod user_apps;
+
 use poise::serenity_prelude as serenity;
 
 type Error = Box<dyn std::error::Error + Send + Sync>;
@@ -75,6 +78,16 @@ async fn main() {
                 subcommand_required::parent_subcommand_required(),
                 track_edits::test_reuse_response(),
                 track_edits::add(),
+                #[cfg(feature = "unstable")]
+                user_apps::everywhere(),
+                #[cfg(feature = "unstable")]
+                user_apps::everywhere_context(),
+                #[cfg(feature = "unstable")]
+                user_apps::user_install(),
+                #[cfg(feature = "unstable")]
+                user_apps::not_in_guilds(),
+                #[cfg(feature = "unstable")]
+                user_apps::user_install_guild(),
             ],
             prefix_options: poise::PrefixFrameworkOptions {
                 prefix: Some("~".into()),
diff --git a/examples/feature_showcase/user_apps.rs b/examples/feature_showcase/user_apps.rs
new file mode 100644
index 000000000000..3abf1c5ae846
--- /dev/null
+++ b/examples/feature_showcase/user_apps.rs
@@ -0,0 +1,60 @@
+use crate::{Context, Error};
+use poise::serenity_prelude as serenity;
+
+// `install_context` determines how the bot has to be installed for a command to be available.
+// `interaction_context` determines where a command can be used.
+
+/// Available everywhere
+#[poise::command(
+    slash_command,
+    install_context = "Guild|User",
+    interaction_context = "Guild|BotDm|PrivateChannel"
+)]
+pub async fn everywhere(ctx: Context<'_>) -> Result<(), Error> {
+    ctx.say("This command is available everywhere!").await?;
+    Ok(())
+}
+
+// also works with `context_menu_command`
+/// Available everywhere
+#[poise::command(
+    context_menu_command = "Everywhere",
+    install_context = "Guild|User",
+    interaction_context = "Guild|BotDm|PrivateChannel"
+)]
+pub async fn everywhere_context(ctx: Context<'_>, msg: serenity::Message) -> Result<(), Error> {
+    msg.reply(ctx, "This context menu is available everywhere!")
+        .await?;
+    Ok(())
+}
+
+/// Available with a user install only
+#[poise::command(
+    slash_command,
+    install_context = "User",
+    interaction_context = "Guild|BotDm|PrivateChannel"
+)]
+pub async fn user_install(ctx: Context<'_>) -> Result<(), Error> {
+    ctx.say("This command is available only with a user install!")
+        .await?;
+    Ok(())
+}
+
+/// Not available in guilds
+#[poise::command(
+    slash_command,
+    install_context = "User",
+    interaction_context = "BotDm|PrivateChannel"
+)]
+pub async fn not_in_guilds(ctx: Context<'_>) -> Result<(), Error> {
+    ctx.say("This command is not available in guilds!").await?;
+    Ok(())
+}
+
+/// User install only in guilds
+#[poise::command(slash_command, install_context = "User", interaction_context = "Guild")]
+pub async fn user_install_guild(ctx: Context<'_>) -> Result<(), Error> {
+    ctx.say("This command is available in guilds only with a user install!")
+        .await?;
+    Ok(())
+}
diff --git a/macros/src/lib.rs b/macros/src/lib.rs
index 5316651af233..a2e4696cd932 100644
--- a/macros/src/lib.rs
+++ b/macros/src/lib.rs
@@ -37,6 +37,8 @@ for example for command-specific help (i.e. `~help command_name`). Escape newlin
 - `category`: Category of this command which affects placement in the help command
 - `custom_data`: Arbitrary expression that will be boxed and stored in `Command::custom_data`
 - `identifying_name`: Optionally, a unique identifier for this command for your personal usage
+- `install_context`: Installation contexts where this command is available (slash-only) (`unstable` feature)
+- `interaction_context`: Interaction contexts where this command is available (slash-only) (`unstable` feature)
 
 ## Checks