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/guides/concepts/connections.md

@@ -1,51 +1,50 @@
 ---
+uid: Guides.Concepts.ManageConnections
 title: Managing Connections
 ---
 
+# Managing Connections with Discord.Net
+
 In Discord.Net, once a client has been started, it will automatically
-maintain a connection to Discord's gateway, until it is manually
+maintain a connection to Discord's gateway until it is manually
 stopped.
 
-### Usage
+## Usage
 
 To start a connection, invoke the `StartAsync` method on a client that
-supports a WebSocket connection.
-
-These clients include the [DiscordSocketClient] and 
-[DiscordRpcClient], as well as Audio clients.
-
-To end a connection, invoke the `StopAsync` method. This will
-gracefully close any open WebSocket or UdpSocket connections.
+supports a WebSocket connection; to end a connection, invoke the
+`StopAsync` method, which gracefully closes any open WebSocket or
+UdpSocket connections.
 
 Since the Start/Stop methods only signal to an underlying connection
-manager that a connection needs to be started, **they return before a 
-connection is actually made.**
+manager that a connection needs to be started, **they return before a
+connection is made.**
 
-As a result, you will need to hook into one of the connection-state
+As a result, you need to hook into one of the connection-state
 based events to have an accurate representation of when a client is
 ready for use.
 
 All clients provide a `Connected` and `Disconnected` event, which is
 raised respectively when a connection opens or closes. In the case of
-the DiscordSocketClient, this does **not** mean that the client is
+the [DiscordSocketClient], this does **not** mean that the client is
 ready to be used.
 
-A separate event, `Ready`, is provided on DiscordSocketClient, which
+A separate event, `Ready`, is provided on [DiscordSocketClient], which
 is raised only when the client has finished guild stream or guild
-sync, and has a complete guild cache.
+sync and has a completed guild cache.
 
 [DiscordSocketClient]: xref:Discord.WebSocket.DiscordSocketClient
-[DiscordRpcClient]: xref:Discord.Rpc.DiscordRpcClient
 
 ### Samples
 
 [!code-csharp[Connection Sample](samples/events.cs)]
 
-### Tips
+## Reconnection
 
-Avoid running long-running code on the gateway! If you deadlock the
-gateway (as explained in [events]), the connection manager will be
-unable to recover and reconnect.
+> [!TIP]
+> Avoid running long-running code on the gateway! If you deadlock the
+> gateway (as explained in [events]), the connection manager will
+> **NOT** be able to recover and reconnect.
 
 Assuming the client disconnected because of a fault on Discord's end,
 and not a deadlock on your end, we will always attempt to reconnect
@@ -53,6 +52,6 @@ and resume a connection.
 
 Don't worry about trying to maintain your own connections, the
 connection manager is designed to be bulletproof and never fail - if
-your client doesn't manage to reconnect, you've found a bug!
+your client does not manage to reconnect, you have found a bug!
 
-[events]: events.md
+[events]: xref:Guides.Concepts.Events

docs/guides/concepts/entities.md

@@ -1,23 +1,26 @@
 ---
+uid: Guides.Concepts.Entities
 title: Entities
 ---
 
->[!NOTE]
-This article is written with the Socket variants of entities in mind,
-not the general interfaces or Rest/Rpc entities.
+# Entities in Discord.Net
+
+> [!NOTE]
+> This article is written with the Socket variants of entities in mind,
+> not the general interfaces or Rest/Rpc entities.
 
 Discord.Net provides a versatile entity system for navigating the
 Discord API.
 
-### Inheritance
+## Inheritance
 
 Due to the nature of the Discord API, some entities are designed with
 multiple variants; for example, `SocketUser` and `SocketGuildUser`.
 
 All models will contain the most detailed version of an entity
-possible, even if the type is less detailed. 
+possible, even if the type is less detailed.
 
-For example, in the case of the `MessageReceived` event, a 
+For example, 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
@@ -28,44 +31,36 @@ But that doesn't mean a message _can't_ come from a
 retrieve information about a guild from a message entity, you will
 need to cast its channel object to a `SocketTextChannel`.
 
-### Navigation
+You can find out various types of entities in the @FAQ.Misc.Glossary
+page.
+
+## 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 Entities
+## Accessing 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.
 
->[!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
+> [!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.
 
 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 
+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.
 
-### Samples
+## Sample
 
-[!code-csharp[Entity Sample](samples/entities.cs)]
-
-### Tips
-
-Avoid using boxing-casts to coerce entities into a variant, use the
-[`as`] keyword, and a null-conditional operator instead.
-
-This allows you to write safer code and avoid [InvalidCastExceptions].
-
-For example, `(message.Author as SocketGuildUser)?.Nickname`.
-
-[`as`]: https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/as
-[InvalidCastExceptions]: https://msdn.microsoft.com/en-us/library/system.invalidcastexception(v=vs.110).aspx
+[!code-csharp[Entity Sample](samples/entities.cs)]

docs/guides/concepts/events.md

@@ -1,16 +1,19 @@
 ---
+uid: Guides.Concepts.Events
 title: Working with Events
 ---
 
+# Events in Discord.Net
+
 Events in Discord.Net are consumed in a similar manner to the standard
 convention, with the exception that every event must be of the type
-`System.Threading.Tasks.Task` and instead of using `EventArgs`, the
-event's parameters are passed directly into the handler.
+@System.Threading.Tasks.Task and instead of using @System.EventArgs,
+the event's parameters are passed directly into the handler.
 
 This allows for events to be handled in an async context directly
 instead of relying on `async void`.
 
-### Usage
+## Usage
 
 To receive data from an event, hook into it using C#'s delegate
 event pattern.
@@ -18,7 +21,7 @@ event pattern.
 You may either opt to hook an event to an anonymous function (lambda)
 or a named function.
 
-### Safety
+## Safety
 
 All events are designed to be thread-safe; events are executed
 synchronously off the gateway task in the same context as the gateway
@@ -39,7 +42,7 @@ a deadlock that will be impossible to recover from.
 Exceptions in commands will be swallowed by the gateway and logged out
 through the client's log method.
 
-### Common Patterns
+## Common Patterns
 
 As you may know, events in Discord.Net are only given a signature of
 `Func<T1, ..., Task>`. There is no room for predefined argument names,
@@ -49,7 +52,7 @@ directly.
 That being said, there are a variety of common patterns that allow you
 to infer what the parameters in an event mean.
 
-#### Entity, Entity
+### Entity, Entity
 
 An event handler with a signature of `Func<Entity, Entity, Task>`
 typically means that the first object will be a clone of the entity
@@ -58,10 +61,10 @@ model of the entity _after_ the change was made.
 
 This pattern is typically only found on `EntityUpdated` events.
 
-#### Cacheable
+### Cacheable
 
 An event handler with a signature of `Func<Cacheable, Entity, Task>`
-means that the `before`	state of the entity was not provided by the
+means that the `before` state of the entity was not provided by the
 API, so it can either be pulled from the client's cache or
 downloaded from the API.
 
@@ -70,15 +73,12 @@ object.
 
 [Cacheable]: xref:Discord.Cacheable`2
 
-### Samples
+> [!NOTE]
+> Many events relating to a Message entity (i.e., `MessageUpdated` and
+> `ReactionAdded`) rely on the client's message cache, which is
+> **not** enabled by default. Set the `MessageCacheSize` flag in
+> @Discord.WebSocket.DiscordSocketConfig to enable it.
+
+## Sample
 
 [!code-csharp[Event Sample](samples/events.cs)]
-
-### Tips
-
-Many events relating to a Message entity (i.e. `MessageUpdated` and 
-`ReactionAdded`) rely on the client's message cache, which is
-**not** enabled by default. Set the `MessageCacheSize` flag in
-[DiscordSocketConfig] to enable it.
-
-[DiscordSocketConfig]: xref:Discord.WebSocket.DiscordSocketConfig

docs/guides/concepts/logging.md

@@ -1,19 +1,28 @@
 ---
-title: Logging
+uid: Guides.Concepts.Logging
+title: Logging Events/Data
 ---
 
-Discord.Net's clients provide a [Log] event that all messages will be
-disbatched over.
+# Logging in Discord.Net
+
+Discord.Net's clients provide a log event that all messages will be
+dispatched over.
 
 For more information about events in Discord.Net, see the [Events]
 section.
 
-[Log]: xref:Discord.Rest.BaseDiscordClient#Discord_Rest_BaseDiscordClient_Log
-[Events]: events.md
+[Events]: xref:Guides.Concepts.Events
 
-### Usage
+> [!WARNING]
+> Due to the nature of Discord.Net's event system, all log event
+> handlers will be executed synchronously on the gateway thread. If your
+> log output will be dumped to a Web API (e.g., Sentry), you are advised
+> to wrap your output in a `Task.Run` so the gateway thread does not
+> become blocked while waiting for logging data to be written.
 
-To receive log events, simply hook the discord client's log method
+## Usage in Client(s)
+
+To receive log events, simply hook the Discord client's @Discord.Rest.BaseDiscordClient.Log
 to a `Task` with a single parameter of type [LogMessage].
 
 It is recommended that you use an established function instead of a
@@ -22,10 +31,10 @@ to a logging function to write their own messages.
 
 [LogMessage]: xref:Discord.LogMessage
 
-### Usage in Commands
+## Usage in Commands
 
-Discord.Net's [CommandService] also provides a log event, identical
-in signature to other log events.
+Discord.Net's [CommandService] also provides a @Discord.Commands.CommandService.Log
+event, identical in signature to other log events.
 
 Data logged through this event is typically coupled with a
 [CommandException], where information about the command's context
@@ -34,14 +43,6 @@ and error can be found and handled.
 [CommandService]: xref:Discord.Commands.CommandService
 [CommandException]: xref:Discord.Commands.CommandException
 
-#### Samples
+## Sample
 
 [!code-csharp[Logging Sample](samples/logging.cs)]
-
-#### Tips
-
-Due to the nature of Discord.Net's event system, all log event
-handlers will be executed synchronously on the gateway thread. If your
-log output will be dumped to a Web API (e.g. Sentry), you are advised
-to wrap your output in a `Task.Run` so the gateway thread does not
-become blocked while waiting for logging data to be written.

docs/guides/concepts/samples/connections.cs

@@ -10,7 +10,7 @@ public class Program
 	{
 		_client = new DiscordSocketClient();
 
-		await _client.LoginAsync(TokenType.Bot, "bot token");
+		await _client.LoginAsync(TokenType.Bot, Environment.GetEnvironmentVariable("DiscordToken"));
 		await _client.StartAsync();
 
 		Console.WriteLine("Press any key to exit...");

docs/guides/concepts/samples/entities.cs

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

docs/guides/concepts/samples/events.cs

@@ -14,7 +14,7 @@ public class Program
 		var _config = new DiscordSocketConfig { MessageCacheSize = 100 };
 		_client = new DiscordSocketClient(_config);
 
-		await _client.LoginAsync(TokenType.Bot, "bot token");
+		await _client.LoginAsync(TokenType.Bot, Environment.GetEnvironmentVariable("DiscordToken"));
 		await _client.StartAsync();
 
 		_client.MessageUpdated += MessageUpdated;

docs/guides/concepts/samples/logging.cs

@@ -15,7 +15,7 @@ public class Program
 
 		_client.Log += Log;
 
-		await _client.LoginAsync(TokenType.Bot, "bot token");
+		await _client.LoginAsync(TokenType.Bot, Environment.GetEnvironmentVariable("DiscordToken"));
 		await _client.StartAsync();
 		
 		await Task.Delay(-1);