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

Author: csmir

Discord.Net.sln

@@ -81,3 +81,22 @@ Due to the nature of the Discord API, we will oftentimes need to add a property
 Furthermore, while we will never break the API (outside of interface changes) on minor builds, we will occasionally need to break the ABI, by introducing parameters to a method to match changes upstream with Discord. As such, a minor version increment may require you to recompile your code, and dependencies, such as addons, may also need to be recompiled and republished on the newer version. When a binary breaking change is made, the change will be noted in the release notes.
 
 An increment of the MAJOR component indicates that breaking changes have been made to the library; consumers should check the release notes to determine what changes need to be made.
+
+## Branches
+
+### Release/X.X
+
+Release branch following Major.Minor. Upon release, patches will be pushed to these branches.
+New NuGet releases will be tagged on these branches.
+
+### Dev
+
+Development branch, available on MyGet. This branch is what pull requests are targetted to.
+
+### Feature/X
+
+Branches that target Dev, adding new features. Feel free to explore these branches and give feedback where necessary.
+
+### Docs/X
+
+Usually targets Dev. These branches are used to update documentation with either new features or existing feature rework.

README.md

@@ -53,7 +53,7 @@ able to message.
 You may check the message channel type. Visit [Glossary] to see the
 various types of channels.
 
-[glossary]: xref:FAQ.Glossary#message-channels
+[Glossary]: xref:Guides.Entities.Glossary#channels
 
 ## How can I get the guild from a message?
 

docs/faq/basics/basic-operations.md

@@ -24,6 +24,6 @@ Visit the repo's [release tag] to see the latest public pre-release.
 
 The `DependencyMap` has been replaced with Microsoft's
 [DependencyInjection] Abstractions. An example usage can be seen
-[here](https://github.com/foxbot/DiscordBotBase/blob/csharp/src/DiscordBot/Program.cs#L36).
+[here](https://github.com/Discord-Net-Labs/Discord.Net-Labs/blob/release/3.x/samples/InteractionFramework/Program.cs#L66).
 
 [DependencyInjection]: https://docs.microsoft.com/en-us/aspnet/core/fundamentals/dependency-injection

docs/faq/misc/legacy.md

@@ -16,7 +16,5 @@
       topicUid: FAQ.Commands.Interactions
     - name: Dependency Injection
       topicUid: FAQ.Commands.DI
-- name: Glossary
-  topicUid: FAQ.Glossary
 - name: Legacy or Upgrade
   topicUid: FAQ.Legacy

docs/faq/toc.yml

@@ -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/casting.md

@@ -1,29 +1,19 @@
 ---
-uid: FAQ.Glossary
-title: Common Terminologies / Glossary
+uid: Guides.Entities.Glossary
+title: Glossary & Flowcharts
 ---
 
-# Glossary
+# Entity Types
 
-This is an additional chapter for quick references to various common
-types that you may see within Discord.Net. To see more information
-regarding each type of object, click on the object to navigate
-to our API documentation page where you might find more explanation
-about it.
+A list of all Discord.Net entities, what they can be cast to and what their properties are.
 
-## Common Types
-
-* A **Guild** ([IGuild]) is an isolated collection of users and
-channels, and are often referred to as "servers".
-	- Example: [Discord API](https://discord.gg/jkrBmQR)
-* A **Channel** ([IChannel]) represents a generic channel.
-	- Example: #dotnet_discord-net
-	- See [Channel Types](#channel-types)
+> [!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.
 
-[IGuild]: xref:Discord.IGuild
-[IChannel]: xref:Discord.IChannel
+## Channels
 
-## Channel Types
+![IChannelChart](images/IChannel.png)
 
 ### Message Channels
 * A **Text Channel** ([ITextChannel]) is a message channel from a Guild.
@@ -40,14 +30,11 @@ channels, and are often referred to as "servers".
 	- 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]) (2.0+) is a category that
+* A **Category Channel** ([ICategoryChannel]) is a category that
 holds one or more sub-channels.
-* A **Nested Channel** ([INestedChannel]) (2.0+) is a channel that can
+* A **Nested Channel** ([INestedChannel]) is a channel that can
 exist under a category.
 
-> [!NOTE]
-> A Channel ([IChannel]) can be all types of channels.
-
 [INestedChannel]: xref:Discord.INestedChannel
 [IGuildChannel]: xref:Discord.IGuildChannel
 [IMessageChannel]: xref:Discord.IMessageChannel
@@ -62,17 +49,27 @@ exist under a category.
 [IStageChannel]: xref:Discord.IStageChannel
 [INewsChannel]: xref:Discord.INewsChannel
 
-## Message Types
+## 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
 
-## User Types
+## 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.
@@ -85,7 +82,29 @@ exist under a category.
 [ISelfUser]: xref:Discord.ISelfUser
 [IUser]: xref:Discord.IUser
 
-## Emoji Types
+## 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>`
@@ -95,16 +114,15 @@ exist under a category.
 [Emote]: xref:Discord.Emote
 [Emoji]: xref:Discord.Emoji
 
-
-## Sticker Types
+### 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 Types
+### Activity
 
 * A **Game** ([Game]) refers to a user's game activity.
 * A **Rich Presence** ([RichGame]) refers to a user's detailed