Documentation Overhaul (#1161)

* Add XML docs

* Clean up style switcher

* Squash commits on branch docs/faq-n-patches

* Fix broken theme selector

* Add local image embed instruction

* Add a bunch of XML docs

* Add a bunch of XML docs

* Fix broken search
+ DocFX by default ships with an older version of jQuery, switching to a newer version confuses parts of the DocFX Javascript.

* Minor fixes for CONTRIBUTING.md and README.md

* Clean up filterConfig.yml

+ New config exposes Discord.Net namespace since it has several common public exceptions that may be helpful to users

* Add XML docs

* Read token from Environment Variable instead of hardcode

* Add XMLDocs

* Compress some assets & add OAuth2 URL generator

* Fix sample link & add missing pictures

* Add tag examples

* Fix embed docs consistency

* Add details regarding userbot support

* Add XML Docs

* Add XML Docs

* Add XML Docs

* Minor fixes in documentations
+ Fix unescaped '<'
+ Fix typo

* Fix seealso for preconditions and add missing descriptions

* Add missing exceptions

* Document exposed TypeReaders

* Fix letter-casing for files

* Add 'last modified' plugin

Source: https://github.com/Still34/DocFx.Plugin.LastModified
Licensed under MIT License

* XML Docs

* Fix minor consistencies & redundant impl

* Add properties examples to overwrite

* Fix missing Username prop

* Add warning for bulk-delete endpoint

* Replace note block

* Add BaseSocketClient docs

* Add XML docs

* Replace langword null to code block null instead

- Because DocFX sucks at rendering langword

* Replace all langword placements with code block

* Add more IGuild docs

* Add details to SpotifyGame

* Initial proofread of the articles

* Add explanation for RunMode

* Add event docs

- MessageReceived
- ChannelUpdated/Destroyed/Created

* Fix light theme link color

* Fix xml docs error

* Add partial documentation for audit log impl

* Add documentation for some REST-based objects

* Add partial documentation for audit log objects

* Add more XML comments to quotation mark alias map stuff, including an example

* Add reference to CommandServiceConfig from the util docs'

* Add explanation that if " is removed then it wont work

* Fix missing service provider in example

* Add documentation for new INestedChannel

* Add documentation

* Add documentation for new API version & few events

* Revise guide paragraphs/samples

+ Fix various formatting.
+ Provide a more detailed walkthrough for dependency injection.
+ Add C# note at intro.

* Fix typos & formatting

* Improve group module example

* Small amount to see if I'm doing it right

* Remove/cleanup redundant variables

* Fix EnterTypingState impl for doc inheritance

* Fix Test to resolve changes made in 15b58e

* Improve precondition documentation

+ Add precondition usage sample
+ Add precondition group usage sample
+ Move precondition samples to its own sample folder

* Move samples to individual folders

* Clarify token source

* Cleanup styling of README.md for docs

* Replace InvalidPathChars for NS1.3

* InvalidPathChars does not exist in NS1.3; replaced with GetInvalidPathChars instead.

* Add a missing change for 2c7cc738

* Update LastModified to v1.1.0 & add license

* Rewrite installation page for Core 2.1

* Fix anchor link

* Bump post-processor to v1.1.1

* Add fixes to partial file & add license

* Moved theme-switcher code to scripts partial file
+ Add author's MIT license to featherlight javascript

* Remove unused bootstrap plugin

* Bump LastModified plugin

* Changed the path from 'lastmodified' to 'last-modified' for consistency

* Cleanup README & Contribution guide

* Changes to last pr

* Fix GetCategoryAsync docs

* Proofread and cleanup articles

* Change passive voice in "Get Started" to active
* Fix improper preposition in Commands Introduction page
* Fix minor grammar mistakes in "Your First Bot" (future tense -> present tense/subjunctive mood -> indicative mood/proper noun casing/incorrect noun/add missing article)
* Fix minor grammar mistakes in "Installation" (missing article)

* no hablo ingles

* Try try try again

* I'm sure you're having as much fun as I am

* Cleanup TOC & fix titles

* Improve styling

+ Change title font to Noto Sans
+ Add materialized design for commit message box

* Add DescriptionGenerator plugin

* Add nightly section for clarification

* Fix typos in Nightlies & Post-execution

* Bump DescriptionGenerator to v1.1.0

+ This build adds the functionality of generating managed references' summary into the description tag.

* Initial emoji article draft

* Add 'additional information' section for emoji article

* Add cosmetic changes to the master css

* Alter info box color
+ Add transition to article content

* Add clarification in the emoji article

* Emphasize that normal emoji string will not translate to its Unicode representation.
* Clean up or add some of the samples featured in the article.
+ Add emoji/emote declaration section for clarification.
+ Add WebSocket emote sample.
- Remove inconsistent styling ('wacky memes' proves to be too out of place).

* Improve readability for nightlies article

* Move 'Bundled Preconditions' section

* Bump LastModified to fix UTC DateTime parsing

* Add langwordMapping.yml

* Add XML docs

* Add VSC workspace rule

* The root workspace limits the ruler to 120 characters for member documentations and excludes folders such as 'samples' and 'docs'.
* The docs workspace limits the ruler to 70 characters for standard conceptual article to comply with documentation's CONTRIBUTING.md rule, and excludes temprorary folders created by DocFX.

* Update CONTRIBUTING.md

* Add documentation style rule

* Fix styling of several member documentation

* Fix ' />' caused by Agent Smith oddities
* Fix styling to be more specific about the mention of IDs

* Fix exception summary to comply with official Microsoft Docs style

* References
https://docs.microsoft.com/en-us/dotnet/api/system.argumentnullexception?view=netframework-4.7.2
https://docs.microsoft.com/en-us/dotnet/api/system.platformnotsupportedexception?view=netframework-4.7.2
https://docs.microsoft.com/en-us/dotnet/api/system.badimageformatexception?view=netframework-4.7.2

* Add XML documentations

* Shift color return docs

* Fix minor docs

* Added documentation for SocketDMChannel, SocketGuildChannel, and SocketTextChannel

* Add XML docs

* Corrections to SocketGuildChannel

* Corrections to SocketTextChannel

* Corrections to SocketDMChannel

* Swapped out 'id' for 'snowflake identifier

* Swapped out 'id' for 'snowflake identifier'

* SocketDMChannel amendments

* SocketGuildChannel amendments

* SocketTextChannel amendments

* Add XML docs & patch return types
+ Starting from this commit, all return types for tasks will use style similar to most documentations featured on docs.microsoft.com

References:
https://docs.microsoft.com/en-us/dotnet/api/microsoft.entityframeworkcore.dbcontext.-ctor?view=efcore-2.1
https://docs.microsoft.com/en-us/dotnet/api/system.io.filestream.readasync?view=netcore-2.1
https://docs.microsoft.com/en-us/dotnet/api/system.io.textwriter.writelineasync?view=netcore-2.1#System_IO_TextWriter_WriteLineAsync_System_Char___
And many more other asynchronous method documentations featured in the latest BCL.

* Added documentation for many audit log data types, fixed vowel indefinite articles

* Change audit log data types to start with 'Contains' (verb) instead of an article

* Fix some documentation issues and document some more audit log data types

* Fix English posession

* Add XML doc

* Documented two more types

* Documented RoleCreateAuditLogData

* Document remaining audit log data types

* Added RestDMChannel documentation

* Added RestGuildChannel documentation

* Added RestTextChannel documentation

* Added RestVoiceChannel documentation

* Added RestUser documentation

* Added RestRole documentation

* Added RestMessage documentation

* Slightly better wording

* Contains -> Contains a piece of (describe article)

* [EN] Present perf. -> past perf.

* Add XML docs

* Fix arrow alignment

* Clarify supported nullable type

* Fixed a typo in ISnowflakeEntity

* Added RestUser Documentation

* Added RestInvite documentation

* Add XML docs & minor optimizations

* Minor optimization for doc rendering

* Rollback font optimization changes

* Amendments to RestUser

* Added SocketDMChannel documentation

* Added RestDMChannel documentation

* Added RestGuild documentation

* Adjustment to SocketDMChannel

* Added minimal descriptions from the API documentation for Integration types

* Added obsolete mention to the ReadMessages flag.

* Added remarks about 2FA requirement for guild permissions

* Added xmldoc for GuildPermission methods

* Added xml doc for ToAllowList and ToDenyList

* Added specification of how the bits of the color raw value are packed

* Added discord API documentation to IConnection interface

* I can spell :^)

* Fix whitespace in ChannelPermission

* fix spacing of values in guildpermission

* Made changes to get field descriptions from feedback, added returns tag to IConnection

* Added property get standard for IntegrationAccount

* Added property get pattern to xml docs and identical returns tag.

* Change all color class references to struct
...because it isn't a class.

* Add XML docs

* Rewrote the returns tags in IGuildIntegration, removed the ones I was unsure about.

* Rewrote the rest of the returns tags

* Amendments

* Cleanup doc for c1d78189

* Added types to <returns> tags where missing

* Added second sample for adding reactions

* Added some class summaries

* Missed a period

* Amendments

* restored the removed line break

* Removed unnecessary see tag

* Use consistent quotation marks around subscribers, the name for these users are dependant on the source of where they are integrated from (youtube or twitch), so we should not use a name that is specific to one platform

* Add <remarks> tag to the IGuildIntegration xmldocs

* Fix grammar issue

* Update DescriptionGenerator

* Cleanup of https://github.com/Still34/Discord.Net/pull/8

* Cleanup previous PR

* Fix for misleading behaviour in the emoji guide
+ Original lines stated that sending a emoji wrapped in colon will not be parsed, but that was incorrect; replaced with reactions instead of sending messages as the example

* Add strings for dictionary in DotSettings

* Add XML docs

* Fix lots of typos in comments
+ Geez, I didn't know there were so many.

* Add XML docs & rewrite GetMessagesAsync docs

This commit rewrites the remarks section of GetMessagesAsync, as well as adding examples to several methods.

* Update 'Your First Bot'
+ This commit reflects the new changes made to the Discord Application Developer Portal after its major update

* Initial optimization for DocFX render & add missing files

* Add examples in message methods

* Cleanup https://github.com/RogueException/Discord.Net/pull/1128

* Fix first bot note

* Cleanup FAQ structure

* Add XML docs

* Update docfx plugins

* Fix navbar collapsing issue

* Fix broken xref

* Cleanup FAQ section
+ Add introductory paragraphs to each FAQ section.
+ Add 'missing dependency' entry to commands FAQ.
* Split commands FAQ to 'General' and 'DI' sections.

* Cleanup https://github.com/RogueException/Discord.Net/pull/1139

* Fix missing namespace

* Add missing highlighting css for the light theme

* Add additional clarification for installing packages

* Add indentation to example for clarity

* Cleanup several articles to be more human-friendly and easier to read

* Remove RPC-related notes

* Cleanup slow-mode-related documentation strings

* Add an additional note about cross-guild emote usage

* Add CreateTextChannel sample

* Add XMLDocs

docs/faq/basics/basic-operations.md

@@ -0,0 +1,123 @@
+---
+uid: FAQ.Basics.BasicOp
+title: Questions about Basic Operations
+---
+
+# Basic Operations Questions
+
+In the following section, you will find commonly asked questions and
+answers regarding basic usage of the library, as well as
+language-specific tips when using this library.
+
+## How should I safely check a type?
+
+> [!WARNING]
+> Direct casting (e.g., `(Type)type`) is **the least recommended**
+> way of casting, as it *can* throw an [InvalidCastException]
+> when the object isn't the desired type.
+>
+> Please refer to [this post] for more details.
+
+In Discord.Net, the idea of polymorphism is used throughout. You may
+need to cast the object as a certain type before you can perform any
+action.
+
+A good and safe casting example:
+
+[!code-csharp[Casting](samples/cast.cs)]
+
+[InvalidCastException]: https://docs.microsoft.com/en-us/dotnet/api/system.invalidcastexception
+[this post]: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/types/how-to-safely-cast-by-using-as-and-is-operators
+
+## How do I send a message?
+
+> [!TIP]
+> The [GetChannel] method by default returns an [IChannel], allowing
+> channel types such as [IVoiceChannel], [ICategoryChannel]
+> to be returned; consequently, you cannot send a message
+> to channels like those.
+
+Any implementation of [IMessageChannel] has a [SendMessageAsync]
+method. You can get the channel via [GetChannel] under the client.
+Remember, when using Discord.Net, polymorphism is a common recurring
+theme. This means an object may take in many shapes or form, which
+means casting is your friend. You should attempt to cast the channel
+as an [IMessageChannel] or any other entity that implements it to be
+able to message.
+
+[SendMessageAsync]: xref:Discord.IMessageChannel.SendMessageAsync*
+[GetChannel]: xref:Discord.WebSocket.DiscordSocketClient.GetChannel*
+
+## How can I tell if a message is from X, Y, Z channel?
+
+You may check the message channel type. Visit [Glossary] to see the
+various types of channels.
+
+[Glossary]: xref:FAQ.Glossary#message-channels
+
+## How can I get the guild from a message?
+
+There are 2 ways to do this. You can do either of the following,
+
+1. Cast the user as an [IGuildUser] and use its [IGuild] property.
+2. Cast the channel as an [IGuildChannel] and use its [IGuild] property.
+
+## How do I add hyperlink text to an embed?
+
+Embeds can use standard [markdown] in the description field as well
+as in field values. With that in mind, links can be added with
+`[text](link)`.
+
+[markdown]: https://support.discordapp.com/hc/en-us/articles/210298617-Markdown-Text-101-Chat-Formatting-Bold-Italic-Underline-
+
+## How do I add reactions to a message?
+
+Any entity that implements [IUserMessage] has an [AddReactionAsync]
+method. This method expects an [IEmote] as a parameter.
+In Discord.Net, an Emote represents a custom-image emote, while an
+Emoji is a Unicode emoji (standard emoji). Both [Emoji] and [Emote]
+implement [IEmote] and are valid options.
+
+# [Adding a reaction to another message](#tab/emoji-others)
+
+[!code-csharp[Emoji](samples/emoji-others.cs)]
+
+# [Adding a reaction to a sent message](#tab/emoji-self)
+
+[!code-csharp[Emoji](samples/emoji-self.cs)]
+
+***
+
+[AddReactionAsync]: xref:Discord.IUserMessage.AddReactionAsync*
+
+## What is a "preemptive rate limit?"
+
+A preemptive rate limit is Discord.Net's way of telling you to slow
+down before you get hit by the real rate limit. Hitting a real rate
+limit might prevent your entire client from sending any requests for
+a period of time. This is calculated based on the HTTP header
+returned by a Discord response.
+
+## Why am I getting so many preemptive rate limits when I try to add more than one reactions?
+
+This is due to how HTML header works, mistreating
+0.25sec/action to 1sec. This causes the lib to throw preemptive rate
+limit more frequently than it should for methods such as adding
+reactions.
+
+## Can I opt-out of preemptive rate limits?
+
+Unfortunately, not at the moment. See [#401](https://github.com/RogueException/Discord.Net/issues/401).
+
+[IChannel]: xref:Discord.IChannel
+[ICategoryChannel]: xref:Discord.ICategoryChannel
+[IGuildChannel]: xref:Discord.IGuildChannel
+[ITextChannel]: xref:Discord.ITextChannel
+[IGuild]: xref:Discord.IGuild
+[IVoiceChannel]: xref:Discord.IVoiceChannel
+[IGuildUser]: xref:Discord.IGuildUser
+[IMessageChannel]: xref:Discord.IMessageChannel
+[IUserMessage]: xref:Discord.IUserMessage
+[IEmote]: xref:Discord.IEmote
+[Emote]: xref:Discord.Emote
+[Emoji]: xref:Discord.Emoji

docs/faq/basics/client-basics.md

@@ -0,0 +1,66 @@
+---
+uid: FAQ.Basics.ClientBasics
+title: Basic Questions about Client
+---
+
+# Client Basics Questions
+
+In the following section, you will find commonly asked questions and
+answers about common issues that you may face when utilizing the
+various clients offered by the library.
+
+## My client keeps returning 401 upon logging in!
+
+> [!WARNING]
+> Userbot/selfbot (logging in with a user token) is no
+> longer supported with this library starting from 2.0, as
+> logging in under a user account may result in account termination.
+>
+> For more information, see issue [827] & [958], as well as the official
+> [Discord API Terms of Service].
+
+There are few possible reasons why this may occur.
+
+1. You are not using the appropriate [TokenType]. If you are using a
+ bot account created from the Discord Developer portal, you should
+ be using `TokenType.Bot`.
+2. You are not using the correct login credentials. Please keep in
+ mind that a token is **different** from a *client secret*.
+
+[TokenType]: xref:Discord.TokenType
+[827]: https://github.com/RogueException/Discord.Net/issues/827
+[958]: https://github.com/RogueException/Discord.Net/issues/958
+[Discord API Terms of Service]: https://discordapp.com/developers/docs/legal
+
+## How do I do X, Y, Z when my bot connects/logs on? Why do I get a `NullReferenceException` upon calling any client methods after connect?
+
+Your bot should **not** attempt to interact in any way with
+guilds/servers until the [Ready] event fires. When the bot
+connects, it first has to download guild information from
+Discord for you to get access to any server
+information; the client is not ready at this point.
+
+Technically, the [GuildAvailable] event fires once the data for a
+particular guild has downloaded; however, it is best to wait for all
+guilds to be downloaded. Once all downloads are complete, the [Ready]
+event is triggered, then you can proceed to do whatever you like.
+
+[Ready]: xref:Discord.WebSocket.DiscordSocketClient.Ready
+[GuildAvailable]: xref:Discord.WebSocket.BaseSocketClient.GuildAvailable
+
+## How do I get a message's previous content when that message is edited?
+
+If you need to do anything with messages (e.g., checking Reactions,
+checking the content of edited/deleted messages), you must set the
+[MessageCacheSize] in your [DiscordSocketConfig] settings in order to
+use the cached message entity. Read more about it [here](xref:Guides.Concepts.Events#cacheable).
+
+1. Message Cache must be enabled.
+2. Hook the MessageUpdated event. This event provides a *before* and
+ *after* object.
+3. Only messages received *after* the bot comes online will be
+ available in the cache.
+
+[MessageCacheSize]: xref:Discord.WebSocket.DiscordSocketConfig.MessageCacheSize
+[DiscordSocketConfig]: xref:Discord.WebSocket.DiscordSocketConfig
+[MessageUpdated]: xref:Discord.WebSocket.BaseSocketClient.MessageUpdated

docs/faq/basics/getting-started.md

@@ -0,0 +1,79 @@
+---
+uid: FAQ.Basics.GetStarted
+title: Beginner Questions / How to Get Started
+---
+
+# Basic Concepts / Getting Started
+
+In this following section, you will find commonly asked questions and
+answers about how to get started with Discord.Net, as well as basic
+introduction to the Discord API ecosystem.
+
+## How do I add my bot to my server/guild?
+
+You can do so by using the [permission calculator] provided
+by [FiniteReality].
+This tool allows you to set permissions that the bot will be assigned
+with, and invite the bot into your guild. With this method, bots will
+also be assigned a unique role that a regular user cannot use; this
+is what we call a `Managed` role. Because you cannot assign this
+role to any other users, it is much safer than creating a single
+role which, intentionally or not, can be applied to other users
+to escalate their privilege.
+
+[FiniteReality]: https://github.com/FiniteReality/permissions-calculator
+[permission calculator]: https://finitereality.github.io/permissions-calculator
+
+## What is a token?
+
+A token is a credential used to log into an account. This information
+should be kept **private** and for your eyes only. Anyone with your
+token can log into your account. This risk applies to both user
+and bot accounts. That also means that you should **never** hardcode
+your token or add it into source control, as your identity may be
+stolen by scrape bots on the internet that scours through 
+constantly to obtain a token.
+
+## What is a client/user/object ID?
+
+Each user and object on Discord has its own snowflake ID generated
+based on various conditions.
+
+![Snowflake Generation](images/snowflake.png)
+
+Anyone can see the ID; it is public. It is merely used to
+identify an object in the Discord ecosystem. Many things in the
+Discord ecosystem require an ID to retrieve or identify the said
+object.
+
+There are 2 common ways to obtain the said ID.
+
+### [Discord Developer Mode](#tab/dev-mode)
+
+By enabling the developer mode you can right click on most objects
+to obtain their snowflake IDs (please note that this may not apply to
+all objects, such as role IDs, or DM channel IDs).
+
+![Developer Mode](images/dev-mode.png)
+
+### [Escape Character](#tab/escape-char)
+
+You can escape an object by using `\` in front the object in the 
+Discord client. For example, when you do `\@Example#1234` in chat,
+it will return the user ID of the aforementioned user.
+
+![Escaping mentions](images/mention-escape.png)
+
+***
+
+## How do I get the role ID?
+
+> [!WARNING]
+> Right-clicking on the role and copying the ID will **not** work.
+> This will only copy the message ID.
+
+Several common ways to do this:
+
+1. Make the role mentionable and mention the role, and escape it
+  using the `\` character in front.
+2. Inspect the roles collection within the guild via your debugger.

docs/faq/basics/samples/cast.cs

@@ -0,0 +1,15 @@
+public async Task MessageReceivedHandler(SocketMessage msg)
+{
+   // Option 1:
+   // Using the `as` keyword, which will return `null` if the object isn't the desired type.
+   var usermsg = msg as SocketUserMessage;
+   // We bail when the message isn't the desired type.
+   if (msg == null) return;
+   
+   // Option 2:
+   // Using the `is` keyword to cast (C#7 or above only)
+   if (msg is SocketUserMessage usermsg) 
+   {
+      // Do things
+   }
+}

docs/faq/basics/samples/emoji-others.cs

@@ -0,0 +1,18 @@
+// bail if the message is not a user one (system messages cannot have reactions)
+var usermsg = msg as IUserMessage;
+if (usermsg == null) return;
+
+// standard Unicode emojis
+Emoji emoji = new Emoji("👍");
+// or
+// Emoji emoji = new Emoji("\uD83D\uDC4D");
+
+// custom guild emotes
+Emote emote = Emote.Parse("<:dotnet:232902710280716288>");  
+// using Emote.TryParse may be safer in regards to errors being thrown;
+// please note that the method does not verify if the emote exists,
+// it simply creates the Emote object for you.
+
+// add the reaction to the message
+await usermsg.AddReactionAsync(emoji); 
+await usermsg.AddReactionAsync(emote); 

docs/faq/basics/samples/emoji-self.cs

@@ -0,0 +1,17 @@
+// capture the message you're sending in a variable
+var msg = await channel.SendMessageAsync("This will have reactions added.");
+
+// standard Unicode emojis
+Emoji emoji = new Emoji("👍");
+// or
+// Emoji emoji = new Emoji("\uD83D\uDC4D");
+
+// custom guild emotes
+Emote emote = Emote.Parse("<:dotnet:232902710280716288>");  
+// using Emote.TryParse may be safer in regards to errors being thrown;
+// please note that the method does not verify if the emote exists,
+// it simply creates the Emote object for you.
+
+// add the reaction to the message
+await msg.AddReactionAsync(emoji); 
+await msg.AddReactionAsync(emote);