Adding Entity guides, flowcharts, better sample system. (#2054)

* initial

* Interaction glossary entry

* Sharded Interaction sample

* Renames into solution

* Debugging samples

* Modify target location for webhookclient

* Finalizing docs work, resolving docfx errors.

* Adding threaduser to user chart

* Add branch info to readme.

* Edits to user chart

* Resolve format for glossary entries

* Patch sln target

* Issue with file naming fixed

* Patch 1/x for builds

* Appending suggestions

docs/guides/entities/casting.md

@@ -0,0 +1,68 @@
+---
+uid: Guides.Entities.Casting
+title: Casting & Unboxing
+---
+
+# Casting
+
+Casting can be done in many ways, and is the only method to box and unbox types to/from their base definition.
+Casting only works for types that inherit the base type that you want to unbox from.
+`IUser` cannot be cast to `IMessage`.
+
+> [!NOTE]
+> Interfaces **can** be cast to other interfaces, as long as they inherit each other.
+> The same goes for reverse casting. As long as some entity can be simplified into what it inherits, your cast will pass.
+
+## Boxing
+
+A boxed object is the definition of an object that was simplified (or trimmed) by incoming traffic,
+but still owns the data of the originally constructed type. Boxing is an implicit operation.
+
+Through casting, we can **unbox** this type, and access the properties that were unaccessible before.
+
+## Unboxing
+
+Unboxing is the most direct way to access the real definition of an object.
+If we want to return a type from its interface, we can unbox it directly.
+
+[!code-csharp[Unboxing](samples/unboxing.cs)]
+
+## Regular casting
+
+In 'regular' casting, we use the `as` keyword to assign the given type to the object.
+If the boxed type can indeed be cast into given type,
+it will become said type, and its properties can be accessed.
+[!code-csharp[Casting](samples/casting.cs)]
+
+> [!WARNING]
+> If the type you're casting to is null, a `NullReferenceException` will be thrown when it's called.
+> This makes safety casting much more interesting to use, as it prevents this exception from being thrown.
+
+## Safety casting
+
+Safety casting makes sure that the type you're trying to cast to can never be null, as it passes checks upon calling them.
+
+There are 3 different ways to safety cast an object:
+
+### Basic safety casting:
+
+To safety cast an object, all we need to do is check if it is of the member type in a statement.
+If this check fails, it will continue below, making sure we don't try to access null.
+[!code-csharp[Base](samples/safety-cast.cs)]
+
+### Object declaration:
+
+Here we declare the object we are casting to,
+making it so that you can immediately work with its properties without reassigning through regular casting.
+[!code-csharp[Declare](samples/safety-cast-var.cs)]
+
+### Reverse passage:
+
+In previous examples, we want to let code continue running after the check, or if the check fails.
+In this example, the cast will return the entire method (ignoring the latter) upon failure,
+and declare the variable for further use into the method:
+[!code-csharp[Pass](samples/safety-cast-pass.cs)]
+
+> [!NOTE]
+> Usage of `is`, `not` and `as` is required in cast assignment and/or type checks. `==`, `!=` and `=` are invalid assignment,
+> as these operators only apply to initialized objects and not their types.

docs/guides/entities/glossary.md

@@ -0,0 +1,140 @@
+---
+uid: Guides.Entities.Glossary
+title: Glossary & Flowcharts
+---
+
+# Entity Types
+
+A list of all Discord.Net entities, what they can be cast to and what their properties are.
+
+> [!NOTE]
+> All interfaces have the same inheritance tree for both `Socket` and `Rest` entities.
+> Entities with that have been marked red are exclusive to the project they source from.
+
+## Channels
+
+![IChannelChart](images/IChannel.png)
+
+### Message Channels
+* A **Text Channel** ([ITextChannel]) is a message channel from a Guild.
+* A **Thread Channel** ([IThreadChannel]) is a thread channel from a Guild.
+* A **News Channel** ([INewsChannel]) (also goes as announcement channel) is a news channel from a Guild.
+* A **DM Channel** ([IDMChannel]) is a message channel from a DM.
+* A **Group Channel** ([IGroupChannel]) is a message channel from a Group.
+	- This is rarely used due to the bot's inability to join groups.
+* A **Private Channel** ([IPrivateChannel]) is a DM or a Group.
+* A **Message Channel** ([IMessageChannel]) can be any of the above.
+
+### Misc Channels
+* A **Guild Channel** ([IGuildChannel]) is a guild channel in a guild.
+	- This can be any channels that may exist in a guild.
+* A **Voice Channel** ([IVoiceChannel]) is a voice channel in a guild.
+* A **Stage Channel** ([IStageChannel]) is a stage channel in a guild.
+* A **Category Channel** ([ICategoryChannel]) is a category that
+holds one or more sub-channels.
+* A **Nested Channel** ([INestedChannel]) is a channel that can
+exist under a category.
+
+[INestedChannel]: xref:Discord.INestedChannel
+[IGuildChannel]: xref:Discord.IGuildChannel
+[IMessageChannel]: xref:Discord.IMessageChannel
+[ITextChannel]: xref:Discord.ITextChannel
+[IGroupChannel]: xref:Discord.IGroupChannel
+[IDMChannel]: xref:Discord.IDMChannel
+[IPrivateChannel]: xref:Discord.IPrivateChannel
+[IVoiceChannel]: xref:Discord.IVoiceChannel
+[ICategoryChannel]: xref:Discord.ICategoryChannel
+[IChannel]: xref:Discord.IChannel
+[IThreadChannel]: xref:Discord.IThreadChannel
+[IStageChannel]: xref:Discord.IStageChannel
+[INewsChannel]: xref:Discord.INewsChannel
+
+## Messages
+
+![IMessageChart](images/IMessage.png)
+
+* A **Rest Followup Message** ([RestFollowupMessage]) is a message returned by followup on on an interaction.
+* A **Rest Interaction Message** ([RestInteractionMessage]) is a message returned by the interaction's original response.
+* A **Rest User Message** ([RestUserMessage]) is a message sent over rest; it can be any of the above.
+* An **User Message** ([IUserMessage]) is a message sent by a user.
+* A **System Message** ([ISystemMessage]) is a message sent by Discord itself.
+* A **Message** ([IMessage]) can be any of the above.
+
+[RestFollowupMessage]: xref:Discord.Rest.RestFollowupMessage
+[RestInteractionMessage]: xref:Discord.Rest.RestInteractionMessage
+[RestUserMEssage]: xref:Discord.Rest.RestUserMessage
+[IUserMessage]: xref:Discord.IUserMessage
+[ISystemMessage]: xref:Discord.ISystemMessage
+[IMessage]: xref:Discord.IMessage
+
+## Users
+
+![IUserChart](images/IUser.png)
+
+* A **Guild User** ([IGuildUser]) is a user available inside a guild.
+* A **Group User** ([IGroupUser]) is a user available inside a group.
+	- This is rarely used due to the bot's inability to join groups.
+* A **Self User** ([ISelfUser]) is the bot user the client is currently logged in as.
+* An **User** ([IUser]) can be any of the above.
+
+[IGuildUser]: xref:Discord.IGuildUser
+[IGroupUser]: xref:Discord.IGroupUser
+[ISelfUser]: xref:Discord.ISelfUser
+[IUser]: xref:Discord.IUser
+
+## Interactions
+
+![IInteractionChart](images/IInteraction.png)
+
+* A **Slash command** ([ISlashCommandInteraction]) is an application command executed in the text box, with provided parameters.
+* A **Message Command** ([IMessageCommandInteraction]) is an application command targetting a message.
+* An **User Command** ([IUserCommandInteraction]) is an application command targetting a user.
+* An **Application Command** ([IApplicationCommandInteraction]) is any of the above.
+* A **Message component** ([IMessageComponent]) is the interaction of a button being clicked/dropdown option(s) entered.
+* An **Autocomplete Interaction** ([IAutocompleteinteraction]) is an interaction that has been automatically completed.
+* An **Interaction** ([IDiscordInteraction]) is any of the above.
+
+[ISlashCommandInteraction]: xref:Discord.ISlashCommandInteraction
+[IMessageCommandInteraction]: xref:Discord.IMessageCommandInteraction
+[IUserCommandInteraction]: xref:Discord.IUserCommandInteraction
+[IApplicationCommandInteraction]: xref:Discord.IApplicationCommandInteraction
+[IMessageComponent]: xref:Discord.IMessageComponent
+[IAutocompleteinteraction]: xref:Discord.IAutocompleteInteraction
+[IDiscordInteraction]: xref:Discord.IDiscordInteraction
+
+## Other types:
+
+### Emoji
+
+* An **Emote** ([Emote]) is a custom emote from a guild.
+	- Example: `<:dotnet:232902710280716288>`
+* An **Emoji** ([Emoji]) is a Unicode emoji.
+	- Example: `👍`
+
+[Emote]: xref:Discord.Emote
+[Emoji]: xref:Discord.Emoji
+
+### Stickers
+
+* A **Sticker** ([ISticker]) is a standard Discord sticker.
+* A **Custom Sticker ([ICustomSticker]) is a Guild-unique sticker.
+
+[ISticker]: xref:Discord.ISticker
+[ICustomSticker]: xref:Discord.ICustomSticker
+
+### Activity
+
+* A **Game** ([Game]) refers to a user's game activity.
+* A **Rich Presence** ([RichGame]) refers to a user's detailed
+gameplay status.
+	- Visit [Rich Presence Intro] on Discord docs for more info.
+* A **Streaming Status** ([StreamingGame]) refers to user's activity
+for streaming on services such as Twitch.
+* A **Spotify Status** ([SpotifyGame]) (2.0+) refers to a user's
+activity for listening to a song on Spotify.
+
+[Game]: xref:Discord.Game
+[RichGame]: xref:Discord.RichGame
+[StreamingGame]: xref:Discord.StreamingGame
+[SpotifyGame]: xref:Discord.SpotifyGame
+[Rich Presence Intro]: https://discord.com/developers/docs/rich-presence/best-practices

docs/guides/entities/introduction.md

@@ -0,0 +1,87 @@
+---
+uid: Guides.Entities.Intro
+title: Introduction
+---
+
+# Entities in Discord.Net
+
+Discord.Net provides a versatile entity system for navigating the
+Discord API.
+
+> [!TIP]
+> It is **vital** that you use the proper IDs for an entity when using
+> a `GetXXX` method. It is recommended that you enable Discord's
+> _developer mode_ to allow easy access to entity IDs, found in
+> Settings > Appearance > Advanced. Read more about it in the
+> [FAQ](xref:FAQ.Basics.GetStarted) page.
+
+## Inheritance
+
+Due to the nature of the Discord API, some entities are designed with
+multiple variants; for example, `IUser` and `IGuildUser`.
+
+All models will contain the most detailed version of an entity
+possible, even if the type is less detailed.
+
+## Socket & REST
+
+REST entities are retrieved over REST, and will be disposed after use.
+It is suggested to limit the amount of REST calls as much as possible,
+as calls over REST interact with the API, and are thus prone to rate-limits.
+
+- [Learn more about REST](https://restfulapi.net/)
+
+Socket entities are created through the gateway,
+most commonly through `DiscordSocketClient` events.
+These entities will enter the clients' global cache for later use.
+
+In the case of the `MessageReceived` event, a
+`SocketMessage` is passed in with a channel property of type
+`SocketMessageChannel`. All messages come from channels capable of
+messaging, so this is the only variant of a channel that can cover
+every single case.
+
+But that doesn't mean a message _can't_ come from a
+`SocketTextChannel`, which is a message channel in a guild. To
+retrieve information about a guild from a message entity, you will
+need to cast its channel object to a `SocketTextChannel`.
+
+> [!NOTE]
+> You can find out the inheritance tree & definitions of various entities
+> [here](xref:Guides.Entities.Glossary)
+
+## Navigation
+
+All socket entities have navigation properties on them, which allow
+you to easily navigate to an entity's parent or children. As explained
+above, you will sometimes need to cast to a more detailed version of
+an entity to navigate to its parent.
+
+## Accessing Socket Entities
+
+The most basic forms of entities, `SocketGuild`, `SocketUser`, and
+`SocketChannel` can be pulled from the DiscordSocketClient's global
+cache, and can be retrieved using the respective `GetXXX` method on
+DiscordSocketClient.
+
+More detailed versions of entities can be pulled from the basic
+entities, e.g., `SocketGuild.GetUser`, which returns a
+`SocketGuildUser`, or `SocketGuild.GetChannel`, which returns a
+`SocketGuildChannel`. Again, you may need to cast these objects to get
+a variant of the type that you need.
+
+### Sample
+
+[!code-csharp[Socket Sample](samples/socketentities.cs)]
+
+## Accessing REST Entities
+
+REST entities work almost the same as Socket entities, but are much less frequently used.
+To access REST entities, the `DiscordSocketClient`'s `Rest` property is required.
+Another option here is to create your own [DiscordRestClient], independent of the Socket gateway.
+
+[DiscordRestClient]: xref:Discord.Rest.DiscordRestClient
+
+### Sample
+
+[!code-csharp[Rest Sample](samples/restentities.cs)]

docs/guides/entities/samples/casting.cs

@@ -0,0 +1,7 @@
+// Say we have an entity; for the simplicity of this example, it will appear from thin air.
+IChannel channel;
+
+// If we want this to be an ITextChannel so we can access the properties of a text channel inside of a guild, an approach would be:
+ITextChannel textChannel = channel as ITextChannel;
+
+await textChannel.DoSomethingICantWithIChannelAsync();

docs/guides/entities/samples/restentities.cs

@@ -0,0 +1,8 @@
+// RestUser entities expose the accent color and banner of a user.
+// This being one of the few use-cases for requesting a RestUser instead of depending on the Socket counterpart.
+public static EmbedBuilder WithUserColor(this EmbedBuilder builder, IUser user)
+{
+    var restUser = await _client.Rest.GetUserAsync(user.Id);
+    return builder.WithColor(restUser.AccentColor ?? Color.Blue);
+    // The accent color can still be null, so a check for this needs to be done to prevent an exception to be thrown.
+}

docs/guides/entities/samples/safety-cast-pass.cs

@@ -0,0 +1,10 @@
+private void MyFunction(IMessage message)
+{
+    // Here we do the reverse as in the previous examples, and let it continue the code below if it IS an IUserMessage
+    if (message is not IUserMessage userMessage)
+        return;
+
+    // Because we do the above check inline (don't give the statement a body),
+    // the code will still declare `userMessage` as available outside of the above statement.
+    Console.WriteLine(userMessage.Author);
+}

docs/guides/entities/samples/safety-cast-var.cs

@@ -0,0 +1,9 @@
+IUser user;
+
+// Here we can pre-define the actual declaration of said IGuildUser object,
+// so we don't need to cast additionally inside of the statement.
+if (user is IGuildUser guildUser)
+{
+    Console.WriteLine(guildUser.JoinedAt);
+}
+// Check failed.

docs/guides/entities/samples/safety-cast.cs

@@ -0,0 +1,8 @@
+IUser user;
+
+// Here we check if the user is an IGuildUser, if not, let it pass. This ensures its not null.
+if (user is IGuildUser)
+{
+    Console.WriteLine("This user is in a guild!");
+}
+// Check failed.

docs/guides/entities/samples/socketentities.cs

@@ -0,0 +1,11 @@
+public string GetChannelTopic(ulong id)
+{
+	var channel = client.GetChannel(81384956881809408) as SocketTextChannel;
+	return channel?.Topic;
+}
+
+public SocketGuildUser GetGuildOwner(SocketChannel channel)
+{
+	var guild = (channel as SocketGuildChannel)?.Guild;
+	return guild?.Owner;
+}

docs/guides/entities/samples/unboxing.cs

@@ -0,0 +1,9 @@
+IUser user;
+
+// Here we use inline unboxing to make a call to its member (if available) only once.
+
+// Note that if the entity we're trying to cast to is null, this will throw a NullReferenceException.
+Console.WriteLine(((IGuildUser)user).Nickname);
+
+// In case you are certain the entity IS said member, you can also use unboxing to declare variables.
+IGuildUser guildUser = (IGuildUser)user;