docs: Documentation December Update (#1218)

* Fix broken link (#11)

* Fix typos and improve wording

* Add information for IGuildUser

+ Add GetPermission sample
+ Add ModifyAsync remarks

* Add information for IGuildChannel

+ Add ModifyAsync remarks
+ Add GetOverwritePermissionAsync examples

* Add warning for Direction.Around

* Fix indentations and references

* Move IRole.ModifyAsync sample

* Add information for IUser

+ Add example, remarks for Get(Default)AvatarUrl
+ Add example, remarks for GetOrCreateDMChannelAsync
+ Add missing remarks/summary/returns for other properties of the class

* Change verbs used in IVoiceState summary/remarks

* Add additional explanation for IGuildUser.RoleIds

* Change verbs used in IMessage summary/remarks

* Clarify IUserMessage Add/RemoveReactionAsync samples

* Fix command handler sample typo

* Add information for DiscordSocketConfig

+ Add remarks/example to the class
+ Add remarks to AlwaysDownloadUsers

* Fix documentation for SlowMode

* Add additional remarks for Guild/TextChannelProperties

* Update DocFx.Plugins.LastModified to v1.2.0
This should drastically improve docfx build time.

* Add missing dependencies

* Update DocFx.Plugins.LastModified to v1.2.1

Improve performance

* Update DocFx.Plugins.LastModified to v1.2.2

* Clarify deployment.md

+ Rewritten .NET Core deployment strategies for better clarification
    * Split deployment types into framework-dependent and self-contained
    * Clarify the benefits of using different types of publishing
    * Include a sample of how to execute dotnet application with the dotnet command in a TIP dialog for visibility

* Update post-execution article and samples

+ This change is to reflect changes made in https://github.com/RogueException/Discord.Net/pull/1164, where CommandInfo is now passed into the CommandExecuted event as an Optional<T>

* Update DocFX.Plugin.DescriptionGenerator to v1.1.1

* Adjust according to recent CommandExecuted changes

See:
+ f549da50e0
+ 6260749095

* Add further documentation for https://github.com/RogueException/Discord.Net/pull/1037

* Add partial documentation for the precondition helper class

* Include CHANGELOG.md in docs

* Revise post-execution docs
* Fix incorrect Optional<T> usage
* Indent some sample code and add a comment reminding the user that the post-execution basic sample code is not ideal.

* Streamline docs for Attachment
+ This commit also adds further explanation for why Embeds and Attachments are read-only collections

* Add further documentation for MessageActivity and MessageApplication

* Add caching-related docs to ISocketMessageChannel

* Add missing documentation inheritance for SyncPermissionsAsync

* Streamline documentation process

This is done by changing the documentation of the implementations required by interfaces to redirect to the interface method instead (e.g., SocketDMChannel#GetMessagesAsync refer to IMessageChannel.GetMessagesAsync within the remarks of the method).

* Cleanup 92bf8363ca

* Update src/Discord.Net.Core/Entities/Channels/Direction.cs

Co-Authored-By: Still34 <341464@gmail.com>

* Update src/Discord.Net.Core/Entities/Channels/Direction.cs

Co-Authored-By: Still34 <341464@gmail.com>

* Update src/Discord.Net.Core/Entities/Channels/GuildChannelProperties.cs

Co-Authored-By: Still34 <341464@gmail.com>

* Update src/Discord.Net.WebSocket/DiscordSocketConfig.cs

Co-Authored-By: Still34 <341464@gmail.com>

* Update according to PR suggestions

* Reword sentences of deployment article for clarification & remove mention of portability
* Fix typos/grammar errors within TextChannelProperties

* Add the logo SVG to the page navbar

* Implement changing logo image based on theme color using CSS background image

* Add a favicon

* use the purple logomark instead of white

* hack? set the title to navbar svg to read "Discord.Net Docs"

docs/_template/last-modified/plugins/LICENSE

@@ -19,3 +19,11 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+==============================================================================
+
+Humanizer (https://github.com/Humanizr/Humanizer)
+The MIT License (MIT)
+Copyright (c) .NET Foundation and Contributors
+
+==============================================================================

docs/_template/last-modified/plugins/LibGit2Sharp.dll.config

@@ -0,0 +1,4 @@
+<configuration>
+    <dllmap os="linux" cpu="x86-64" wordsize="64" dll="git2-8e0b172" target="lib/linux-x64/libgit2-8e0b172.so" />
+    <dllmap os="osx" cpu="x86,x86-64" dll="git2-8e0b172" target="lib/osx/libgit2-8e0b172.dylib" />
+</configuration>

docs/_template/light-dark-theme/styles/dark.css

@@ -301,4 +301,8 @@ span.arrow-d{
 
 span.arrow-r{
     border-left: 5px solid white
-}
+}
+
+.logo-switcher {
+    background: url("/marketing/logo/SVG/Combinationmark White.svg") no-repeat;
+}

docs/_template/light-dark-theme/styles/gray.css

@@ -308,4 +308,8 @@ span.arrow-d{
 
 span.arrow-r{
     border-left: 5px solid white
-}
+}
+
+.logo-switcher {
+    background: url("/marketing/logo/SVG/Combinationmark White.svg") no-repeat;
+}

docs/_template/light-dark-theme/styles/light.css

@@ -110,4 +110,8 @@ span.arrow-d{
 
 span.arrow-r{
     border-left: 5px solid black
-}
+}
+
+.logo-switcher {
+    background: url("/marketing/logo/SVG/Combinationmark.svg") no-repeat;
+}

docs/_template/light-dark-theme/styles/master.css

@@ -9,6 +9,15 @@ body {
     scroll-behavior: smooth;
 }
 
+#logo
+{
+    max-width: 100px;
+    max-height: 100px;
+    width: 38pt;
+    height: 38pt;
+    padding: 8pt;
+}
+
 p,
 li,
 .toc {
@@ -23,6 +32,15 @@ img {
     margin-bottom: 15px;
 }
 
+.big-logo {
+    display: block;
+    box-shadow: none !important;
+    /* Width value was taken from the original size of the combomark svg */
+    width: 951pt;
+    /* Height was arbitrarily determined */
+    min-height: 100pt;
+}
+
 article.content p{
     -webkit-transition: all .75s ease-in-out;
     transition: all .75s ease-in-out;
@@ -153,4 +171,4 @@ span.arrow-d{
 
 span.arrow-r{
     top: 6px; position: relative;
-}
+}

docs/docfx.json

@@ -24,13 +24,19 @@
       },
       {
         "files": ["guides/**.md", "guides/**/toc.yml"]
+      },
+      {
+        "src": "../",
+        "files": [ "CHANGELOG.md" ]
       }
     ],
     "resource": [{
       "files": [
         "**/images/**",
         "**/samples/**",
-        "langwordMapping.yml"
+        "langwordMapping.yml",
+        "marketing/logo/SVG/**.svg",
+        "favicon.ico"
       ]
     }],
     "dest": "_site",
@@ -45,7 +51,9 @@
     "globalMetadata": {
       "_appTitle": "Discord.Net Documentation",
       "_appFooter": "Discord.Net (c) 2015-2018 2.0.0-beta",
-      "_enableSearch": true
+      "_enableSearch": true,
+      "_appLogoPath": "marketing/logo/SVG/Logomark Purple.svg",
+      "_appFaviconPath":  "favicon.ico"
     },
     "xrefService": [
       "https://xref.docs.microsoft.com/query?uid={uid}"

docs/faq/basics/basic-operations.md

@@ -27,7 +27,7 @@ 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
+[this post]: https://docs.microsoft.com/en-us/dotnet/csharp/how-to/safely-cast-using-pattern-matching-is-and-as-operators
 
 ## How do I send a message?
 

docs/faq/commands/general.md

@@ -119,24 +119,29 @@ The following are the known caveats with `RunMode.Async`,
 3. [ExecuteAsync] will immediately return [ExecuteResult] instead of
  other result types (this is particularly important for those who wish
  to utilize [RuntimeResult] in 2.0).
-4. Exceptions are swallowed.
+4. Exceptions are swallowed in the `ExecuteAsync` result.
 
 However, there are ways to remedy some of these.
 
 For #3, in Discord.Net 2.0, the library introduces a new event called
-[CommandExecuted], which is raised whenever the command is
-**successfully executed**. This event will be raised regardless of
-the `RunMode` type and will return the appropriate execution result.
+[CommandService.CommandExecuted], which is raised whenever the command is executed. 
+This event will be raised regardless of
+the `RunMode` type and will return the appropriate execution result
+and the associated @Discord.Commands.CommandInfo if applicable.
 
 For #4, exceptions are caught in [CommandService.Log] event under
-[LogMessage.Exception] as [CommandException].
+[LogMessage.Exception] as [CommandException] and in the 
+[CommandService.CommandExecuted] event under the [IResult] as 
+[ExecuteResult.Exception].
 
 [Task.Run]: https://docs.microsoft.com/en-us/dotnet/api/system.threading.tasks.task.run
 [async state machine]: https://www.red-gate.com/simple-talk/dotnet/net-tools/c-async-what-is-it-and-how-does-it-work/
 [ExecuteAsync]: xref:Discord.Commands.CommandService.ExecuteAsync*
 [ExecuteResult]: xref:Discord.Commands.ExecuteResult
 [RuntimeResult]: xref:Discord.Commands.RuntimeResult
-[CommandExecuted]: xref:Discord.Commands.CommandService.CommandExecuted
+[CommandService.CommandExecuted]: xref:Discord.Commands.CommandService.CommandExecuted
 [CommandService.Log]: xref:Discord.Commands.CommandService.Log
 [LogMessage.Exception]: xref:Discord.LogMessage.Exception*
-[CommandException]: xref:Discord.Commands.CommandException
+[ExecuteResult.Exception]: xref:Discord.Commands.ExecuteResult.Exception*
+[CommandException]: xref:Discord.Commands.CommandException
+[IResult]: xref:Discord.Commands.IResult

docs/guides/commands/post-execution.md

@@ -31,17 +31,15 @@ be a violation of the SRP (Single Responsibility Principle).
 Another major issue is if your command is marked with
 `RunMode.Async`, [ExecuteAsync] will **always** return a successful
 [ExecuteResult] instead of the actual result. You can learn more
-about the impact in the [FAQ](xref:FAQ.Commands.General).
+about the impact in @FAQ.Commands.General.
 
 ## CommandExecuted Event
 
 Enter [CommandExecuted], an event that was introduced in
 Discord.Net 2.0. This event is raised whenever a command is
-successfully executed **without any run-time exceptions** or **any
-parsing or precondition failure**. This means this event can be
-used to streamline your post-execution design, and the best thing
-about this event is that it is not prone to `RunMode.Async`'s
-[ExecuteAsync] drawbacks.
+executed regardless of its execution status. This means this 
+event can be used to streamline your post-execution design,
+is not prone to `RunMode.Async`'s [ExecuteAsync] drawbacks.
 
 Thus, we can begin working on code such as:
 

docs/guides/commands/samples/intro/command_handler.cs

@@ -49,7 +49,7 @@ public class CommandHandler
         
         // Keep in mind that result does not indicate a return value
         // rather an object stating if the command executed successfully.
-        var result = await _command.ExecuteAsync(
+        var result = await _commands.ExecuteAsync(
             context: context, 
             argPos: argPos,
             services: null);

docs/guides/commands/samples/post-execution/command_executed_adv_demo.cs

@@ -1,4 +1,4 @@
-public async Task OnCommandExecutedAsync(CommandInfo command, ICommandContext context, IResult result)
+public async Task OnCommandExecutedAsync(Optional<CommandInfo> command, ICommandContext context, IResult result)
 {
     switch(result)
     {

docs/guides/commands/samples/post-execution/command_executed_demo.cs

@@ -6,7 +6,7 @@ public async Task SetupAsync()
     // Hook the command handler
     _client.MessageReceived += HandleCommandAsync;
 }
-public async Task OnCommandExecutedAsync(CommandInfo command, ICommandContext context, IResult result)
+public async Task OnCommandExecutedAsync(Optional<CommandInfo> command, ICommandContext context, IResult result)
 {
     // We have access to the information of the command executed,
     // the context of the command, and the result returned from the
@@ -20,19 +20,19 @@ public async Task OnCommandExecutedAsync(CommandInfo command, ICommandContext co
 
     // ...or even log the result (the method used should fit into
     // your existing log handler)
-    await _log.LogAsync(new LogMessage(LogSeverity.Info, "CommandExecution", $"{command?.Name} was executed at {DateTime.UtcNow}."));
+    var commandName = command.IsSpecified ? command.Value.Name : "A command";
+    await _log.LogAsync(new LogMessage(LogSeverity.Info, 
+        "CommandExecution", 
+        $"{commandName} was executed at {DateTime.UtcNow}."));
 }
 public async Task HandleCommandAsync(SocketMessage msg)
 {
     var message = messageParam as SocketUserMessage;
     if (message == null) return;
     int argPos = 0;
-    if (!(message.HasCharPrefix('!', ref argPos) || message.HasMentionPrefix(_client.CurrentUser, ref argPos)) || message.Author.IsBot) return;
+    if (!(message.HasCharPrefix('!', ref argPos) || 
+        message.HasMentionPrefix(_client.CurrentUser, ref argPos)) || 
+        message.Author.IsBot) return;
     var context = new SocketCommandContext(_client, message);
-    var result = await _commands.ExecuteAsync(context, argPos, _services);
-    // Optionally, you may pass the result manually into your
-    // CommandExecuted event handler if you wish to handle parsing or
-    // precondition failures in the same method.
-
-    // await OnCommandExecutedAsync(null, context, result);
+    await _commands.ExecuteAsync(context, argPos, _services);
 }

docs/guides/commands/samples/post-execution/post-execution_basic.cs

@@ -1,11 +1,14 @@
+// Bad code!!!
 var result = await _commands.ExecuteAsync(context, argPos, _services);
 if (result.CommandError != null)
 	switch(result.CommandError)
 	{
 		case CommandError.BadArgCount:
-			await context.Channel.SendMessageAsync("Parameter count does not match any command's.");
+			await context.Channel.SendMessageAsync(
+				"Parameter count does not match any command's.");
 			break;
 		default:
-			await context.Channel.SendMessageAsync($"An error has occurred {result.ErrorReason}");
+			await context.Channel.SendMessageAsync(
+				$"An error has occurred {result.ErrorReason}");
 			break;
 	}

docs/guides/deployment/deployment.md

@@ -52,33 +52,50 @@ enough. Here is a list of recommended VPS provider.
 
 > [!NOTE]
 > This section only covers the very basics of .NET Core deployment.
-> To learn more about deployment, visit [.NET Core application deployment]
-> by Microsoft.
+> To learn more about .NET Core deployment, 
+> visit [.NET Core application deployment] by Microsoft.
 
-By default, .NET Core compiles all projects as a DLL file, so that any
-.NET Core runtime can execute the application.
+When redistributing the application - whether for deployment on a
+remote machine or for sharing with another user - you may want to
+publish the application; in other words, to create a
+self-contained package without installing the dependencies
+and the runtime on the target platform.
 
-You may execute the application via `dotnet myprogram.dll` assuming you
-have the dotnet CLI installed.
+### Framework-dependent Deployment
 
-When redistributing the application, you may want to publish the
-application, or in other words, create a self-contained package
-for use on another machine without installing the dependencies first.
-
-This can be achieved by using the dotnet CLI too on the development
-machine:
+To deploy a framework-dependent package (i.e. files to be used on a
+remote machine with the `dotnet` command), simply publish
+the package with:
 
 * `dotnet publish -c Release`
 
-Additionally, you may want to target a specific platform when
-publishing the application so you may use the application without
-having to install the Core runtime on the target machine. To do this,
-you may specify an [Runtime ID] upon build/publish with the `-r`
-option.
+This will create a package with the **least dependencies**
+included with the application; however, the remote machine
+must have `dotnet` runtime installed before the remote could run the
+program.
 
-For example, when targeting a Windows 10 machine, you may want to use
-the following to create the application in Windows executable
-format (.exe):
+> [!TIP]
+> Do not know how to run a .NET Core application with 
+> the `dotnet` runtime? Navigate to the folder of the program 
+> (typically under `$projFolder/bin/Release`) and 
+> enter `dotnet program.dll` where `program.dll` is your compiled
+> binaries.
+
+### Self-contained Deployment
+
+To deploy a self-contained package (i.e. files to be used on a remote
+machine without the `dotnet` runtime), publish with a specific
+[Runtime ID] with the `-r` switch.
+
+This will create a package with dependencies compiled for the target
+platform, meaning that all the required dependencies will be included
+with the program. This will result in **larger package size**; 
+however, that means the copy of the runtime that can be run
+natively on the target platform.
+
+For example, the following command will create a Windows 
+executable (`.exe`) that is ready to be executed on any
+Windows 10 x64 based machine:
 
 * `dotnet publish -c Release -r win10-x64`
 

docs/index.md

@@ -5,6 +5,8 @@ title: Home
 
 # Discord.Net Documentation
 
+<img class="big-logo logo-switcher" />
+
 ## What is Discord.Net?
 
 Discord.Net is an asynchronous, multi-platform .NET Library used to
@@ -25,4 +27,4 @@ objects in the library.
 - [GitHub](https://github.com/RogueException/Discord.Net/)
 - [NuGet](https://www.nuget.org/packages/Discord.Net/)
 - [MyGet Feed](https://www.myget.org/feed/Packages/discord-net) - Add-ons and nightly builds
-- [AppVeyor CI](https://ci.appveyor.com/project/RogueException/discord-net) - Nightly builds via Continuous Integration
+- [AppVeyor CI](https://ci.appveyor.com/project/RogueException/discord-net) - Nightly builds via Continuous Integration

docs/marketing/logo/SVG/Logomark Purple.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 265.74 274.24"><defs><style>.cls-1{fill:#68217a;}.cls-2{fill:#939;}</style></defs><title>Logomark Purple</title><g id="Layer_2" data-name="Layer 2"><g id="Layer_1-2" data-name="Layer 1"><path class="cls-1" d="M54.48.13,239.93,17.62A28.57,28.57,0,0,1,265.61,48.8L248,235.91a28.57,28.57,0,0,1-31.06,25.84L60,246.94,69.71,222l-19.27,14.8L32.23,250.75,0,274.24,23.42,26A28.56,28.56,0,0,1,54.48.13Z"/><rect class="cls-2" x="113.88" y="-22.58" width="16.56" height="138.01" rx="6.32" transform="translate(63.14 163.03) rotate(-83.96)"/><rect class="cls-2" x="157.3" y="20.84" width="16.56" height="138.01" rx="6.32" transform="translate(58.81 245.05) rotate(-83.96)"/><rect class="cls-2" x="100.92" y="99.96" width="16.56" height="138.01" rx="6.32" transform="translate(-70.32 259.78) rotate(-83.96)"/><rect class="cls-2" x="153.11" y="60.4" width="16.56" height="138.01" rx="6.32" transform="translate(15.73 276.29) rotate(-83.96)"/></g></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 265.74 274.24"><defs><style>.cls-1{fill:#68217a;}.cls-2{fill:#939;}</style></defs><title>Discord.Net Docs</title><g id="Layer_2" data-name="Layer 2"><g id="Layer_1-2" data-name="Layer 1"><path class="cls-1" d="M54.48.13,239.93,17.62A28.57,28.57,0,0,1,265.61,48.8L248,235.91a28.57,28.57,0,0,1-31.06,25.84L60,246.94,69.71,222l-19.27,14.8L32.23,250.75,0,274.24,23.42,26A28.56,28.56,0,0,1,54.48.13Z"/><rect class="cls-2" x="113.88" y="-22.58" width="16.56" height="138.01" rx="6.32" transform="translate(63.14 163.03) rotate(-83.96)"/><rect class="cls-2" x="157.3" y="20.84" width="16.56" height="138.01" rx="6.32" transform="translate(58.81 245.05) rotate(-83.96)"/><rect class="cls-2" x="100.92" y="99.96" width="16.56" height="138.01" rx="6.32" transform="translate(-70.32 259.78) rotate(-83.96)"/><rect class="cls-2" x="153.11" y="60.4" width="16.56" height="138.01" rx="6.32" transform="translate(15.73 276.29) rotate(-83.96)"/></g></g></svg>

docs/toc.yml

@@ -6,4 +6,6 @@
   topicUid: FAQ.Basics.GetStarted
 - name: API Documentation
   href: api/
-  topicUid: API.Docs
+  topicUid: API.Docs
+- name: Changelog
+  topicHref: ../CHANGELOG.md