FAQ rework, replacing outdated info, better interaction FAQ (#2106)

* FAQ rework, replacing outdated info, better interaction faq

* Update docs/faq/basics/getting-started.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update docs/faq/basics/getting-started.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* Update docs/faq/int_framework/general.md

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>

* fix TOC reference

Co-authored-by: Jared L <48422312+lhjt@users.noreply.github.com>
Co-authored-by: Quin Lynch <lynchquin@gmail.com>

docs/faq/int_framework/framework.md

@@ -0,0 +1,71 @@
+---
+uid: FAQ.Interactions.Framework
+title: Interaction Framework
+---
+
+# The Interaction Framework
+
+Common misconceptions and questions about the Interaction Framework.
+
+## How can I restrict some of my commands so only specific users can execute them?
+
+Based on how you want to implement the restrictions, you can use the
+built-in `RequireUserPermission` precondition, which allows you to
+restrict the command based on the user's current permissions in the
+guild or channel (*e.g., `GuildPermission.Administrator`,
+`ChannelPermission.ManageMessages`*).
+
+[RequireUserPermission]: xref:Discord.Commands.RequireUserPermissionAttribute
+
+> [!NOTE]
+> There are many more preconditions to use, including being able to make some yourself.
+> Examples on self-made preconditions can be found
+> [here](https://github.com/discord-net/Discord.Net/blob/dev/samples/InteractionFramework/Attributes/RequireOwnerAttribute.cs)
+
+## Why do preconditions not hide my commands?
+
+In the current permission design by Discord,
+it is not very straight forward to limit vision of slash/context commands to users.
+If you want to hide commands, you should take a look at the commands' `DefaultPermissions` parameter.
+
+## Module dependencies aren't getting populated by Property Injection?
+
+Make sure the properties are publicly accessible and publicly settable.
+
+[!code-csharp[Property Injection](samples/propertyinjection.cs)]
+
+## `InteractionService.ExecuteAsync()` always returns a successful result, how do i access the failed command execution results?
+
+If you are using `RunMode.Async` you need to setup your post-execution pipeline around
+`..Executed` events exposed by the Interaction Service.
+
+## How do I check if the executing user has * permission?
+
+Refer to the [documentation about preconditions]
+
+[documentation about preconditions]: xref:Guides.ChatCommands.Preconditions
+
+## How do I send the HTTP Response from inside the command modules.
+
+Set the `RestResponseCallback` property of [InteractionServiceConfig] with a delegate for handling HTTP Responses and use
+`RestInteractionModuleBase` to create your command modules. `RespondWithModalAsync()`, `RespondAsync()` and `DeferAsync()` methods of this module base will use the
+`RestResponseCallback` to create interaction responses.
+
+## Is there a cleaner way of creating parameter choices other than using `[Choice]`?
+
+The default `enum` [TypeConverter] of the Interaction Service will
+automatically register `enum`s as multiple choice options.
+
+## How do I add an optional `enum` parameter but make the default value not visible to the user?
+
+The default `enum` [TypeConverter] of the Interaction Service comes with `[Hide]` attribute that
+can be used to prevent certain enum values from getting registered.
+
+## How does the InteractionService determine the generic TypeConverter to use for a parameter type?
+
+It compares the _target base type_ key of the
+[TypeConverter] and chooses the one that sits highest on the inheritance hierarchy.
+
+[TypeConverter]: xref:Discord.Interactions.TypeConverter
+[Interactions FAQ]: xref: FAQ.Basics.Interactions
+[InteractionServiceConfig]: xref:Discord.Interactions.InteractionServiceConfig

docs/faq/int_framework/general.md

@@ -0,0 +1,67 @@
+---
+uid: FAQ.Interactions.General
+title: Interactions
+---
+
+# Interaction basics
+
+This chapter mostly refers to interactions in general,
+and will include questions that are common among users of the Interaction Framework
+as well as users that register and handle commands manually.
+
+## What's the difference between RespondAsync, DeferAsync and FollowupAsync?
+
+The difference between these 3 functions is in how you handle the command response.
+[RespondAsync] and
+[DeferAsync] let the API know you have succesfully received the command. This is also called 'acknowledging' a command.
+DeferAsync will not send out a response, RespondAsync will.
+[FollowupAsync] follows up on succesful acknowledgement. 
+
+> [!WARNING]
+> If you have not acknowledged the command FollowupAsync will not work! the interaction has not been resonded to, so you cannot follow it up!
+
+[RespondAsync]: xref:Discord.IDiscordInteraction
+[DeferAsync]: xref:Discord.IDiscordInteraction
+[FollowUpAsync]: xref:Discord.IDiscordInteraction
+
+## Im getting System.TimeoutException: 'Cannot respond to an interaction after 3 seconds!'
+
+This happens because your computer's clock is out of sync or you're trying to respond after 3 seconds.
+If your clock is out of sync and you can't fix it, you can set the `UseInteractionSnowflakeDate` to false in the [DiscordSocketConfig].
+
+[!code-csharp[Interaction Sync](samples/interactionsyncing.cs)]
+
+[DiscordClientConfig]: xref:Discord.WebSocket.DiscordSocketConfig
+
+## How do I use this * interaction specific method/property?
+
+If your interaction context holds a down-casted version of the interaction object, you need to up-cast it.
+Ideally, use pattern matching to make sure its the type of interaction you are expecting it to be.
+
+> [!NOTE]
+> Further documentation on pattern matching can be found [here](xref:Guides.Entities.Casting).
+
+## My interaction commands are not showing up?
+
+If you registered your commands globally, it can take up to 1 hour for them to register.
+Did you register a guild command (should be instant), or waited more than an hour and still don't have them show up?
+
+- Try to check for any errors in the console, there is a good chance something might have been thrown.
+
+- Register your commands after the Ready event in the client. The client is not configured to register commands before this moment.
+
+- Check if no bad form exception is thrown; If so, refer to the above question.
+
+- Do you have the application commands scope checked when adding your bot to guilds?
+
+## Do I need to create commands on startup?
+
+If you are registering your commands for the first time, it is required to create them once.
+After this, commands will exist indefinitely until you overwrite them.
+Overwriting is only required if you make changes to existing commands, or add new ones.
+
+## I can't see all of my user/message commands, why?
+
+Message and user commands have a limit of 5 per guild, and another 5 globally.
+If you have more than 5 guild-only message commands being registered, no more than 5 will actually show up.
+You can get up to 10 entries to show if you register 5 per guild, and another 5 globally.

docs/faq/int_framework/manual.md

@@ -0,0 +1,45 @@
+---
+uid: FAQ.Interactions.Manual
+title: Manual handling
+---
+
+# Manually handing interactions.
+
+This section talks about the manual building and responding to interactions.
+If you are using the interaction framework (highly recommended) this section does not apply to you.
+
+## Bad form Exception when I try to create my commands, why do I get this?
+
+Bad form exceptions are thrown if the slash, user or message command builder has invalid values.
+The following options could resolve your error.
+
+#### Is your command name lowercase?
+
+If your command name is not lowercase, it is not seen as a valid command entry.
+`Avatar` is invalid; `avatar` is valid.
+
+#### Are your values below or above the required amount? (This also applies to message components)
+
+Discord expects all values to be below maximum allowed.
+Going over this maximum amount of characters causes an exception.
+
+> [!NOTE]
+> All maximum and minimum value requirements can be found in the [Discord Developer Docs].
+> For components, structure documentation is found [here].
+
+[Discord Developer Docs]: https://discord.com/developers/docs/interactions/application-commands#application-commands
+[here]: https://discord.com/developers/docs/interactions/message-components#message-components
+
+#### Is your subcommand branching correct?
+
+Branching structure is covered properly here: xref:Guides.SlashCommands.SubCommand
+
+![Scope check](images/scope.png)
+
+## There are many options for creating commands, which do I use?
+
+[!code-csharp[Register examples](samples/registerint.cs)]
+
+> [!NOTE]
+> You can use bulkoverwrite even if there are no commands in guild, nor globally.
+> The bulkoverwrite method disposes the old set of commands and replaces it with the new.

docs/faq/int_framework/samples/interactionsyncing.cs

@@ -0,0 +1,6 @@
+DiscordSocketConfig config = new()
+{
+    UseInteractionSnowflakeDate = false
+};
+
+DiscordSocketclient client = new(config);

docs/faq/int_framework/samples/propertyinjection.cs

@@ -0,0 +1,8 @@
+public class MyModule
+{
+    // Intended.
+    public InteractionService Service { get; set; }
+
+    // Will not work. A private setter cannot be accessed by the serviceprovider.
+    private InteractionService Service { get; private set; }
+}

docs/faq/int_framework/samples/registerint.cs

@@ -0,0 +1,21 @@
+private async Task ReadyAsync()
+{
+    // pull your commands from some array, everyone has a different approach for this.
+    var commands = _builders.ToArray();
+
+    // write your list of commands globally in one go.
+    await _client.Rest.BulkOverwriteGlobalCommands(commands);
+
+    // write your array of commands to one guild in one go.
+    // You can do a foreach (... in _client.Guilds) approach to write to all guilds.
+    await _client.Rest.BulkOverwriteGuildCommands(commands, /* some guild ID */);
+
+    foreach (var c in commands)
+    {
+        // Create a global command, repeating usage for multiple commands.
+        await _client.Rest.CreateGlobalCommand(c);
+
+        // Create a guild command, repeating usage for multiple commands.
+        await _client.Rest.CreateGuildCommand(c, guildId);
+    }
+}