From 5b275f66883c30bbc0476fb75ab877702660f680 Mon Sep 17 00:00:00 2001
From: Still Hsu <341464@gmail.com>
Date: Sat, 9 Feb 2019 01:18:40 +0800
Subject: [PATCH] Clarify several guides samples with notes

- Reword TypeReader comment to avoid giving the idea that the sample itself is "obsolete"
- Remove CommandException logging comment regarding C#7.0 as the version is now the standard across VS2017 and up
- Remove suggestion about handling result in command handler since it is now advised to use CommandExecuted instead
+ Add additional comment to clarify ctor for DI setup
---
 .../dependency-injection/dependency_map_setup.cs    |  3 +++
 .../commands/samples/intro/command_handler.cs       | 13 ++-----------
 .../samples/post-execution/command_exception_log.cs |  1 -
 .../commands/samples/typereaders/typereader.cs      |  5 +++--
 4 files changed, 8 insertions(+), 14 deletions(-)

diff --git a/docs/guides/commands/samples/dependency-injection/dependency_map_setup.cs b/docs/guides/commands/samples/dependency-injection/dependency_map_setup.cs
index 118c032ed..16ca479db 100644
--- a/docs/guides/commands/samples/dependency-injection/dependency_map_setup.cs
+++ b/docs/guides/commands/samples/dependency-injection/dependency_map_setup.cs
@@ -3,6 +3,9 @@ public class Initialize
 	private readonly CommandService _commands;
 	private readonly DiscordSocketClient _client;
 
+	// Ask if there are existing CommandService and DiscordSocketClient
+	// instance. If there are, we retrieve them and add them to the
+	// DI container; if not, we create our own.
 	public Initialize(CommandService commands = null, DiscordSocketClient client = null)
 	{
 		_commands = commands ?? new CommandService();
diff --git a/docs/guides/commands/samples/intro/command_handler.cs b/docs/guides/commands/samples/intro/command_handler.cs
index b962cdd6c..480e43c7f 100644
--- a/docs/guides/commands/samples/intro/command_handler.cs
+++ b/docs/guides/commands/samples/intro/command_handler.cs
@@ -3,6 +3,7 @@ public class CommandHandler
     private readonly DiscordSocketClient _client;
     private readonly CommandService _commands;
 
+    // Retrieve client and CommandService instance via ctor
     public CommandHandler(DiscordSocketClient client, CommandService commands)
     {
         _commands = commands;
@@ -46,19 +47,9 @@ public class CommandHandler
 
         // Execute the command with the command context we just
         // created, along with the service provider for precondition checks.
-        
-        // Keep in mind that result does not indicate a return value
-        // rather an object stating if the command executed successfully.
-        var result = await _commands.ExecuteAsync(
+        await _commands.ExecuteAsync(
             context: context, 
             argPos: argPos,
             services: null);
-
-        // Optionally, we may inform the user if the command fails
-        // to be executed; however, this may not always be desired,
-        // as it may clog up the request queue should a user spam a
-        // command.
-        // if (!result.IsSuccess)
-        // await context.Channel.SendMessageAsync(result.ErrorReason);
     }
 }
diff --git a/docs/guides/commands/samples/post-execution/command_exception_log.cs b/docs/guides/commands/samples/post-execution/command_exception_log.cs
index 2956a0203..fa3673e82 100644
--- a/docs/guides/commands/samples/post-execution/command_exception_log.cs
+++ b/docs/guides/commands/samples/post-execution/command_exception_log.cs
@@ -1,6 +1,5 @@
 public async Task LogAsync(LogMessage logMessage)
 {
-    // This casting type requries C#7
     if (logMessage.Exception is CommandException cmdException)
     {
         // We can tell the user that something unexpected has happened
diff --git a/docs/guides/commands/samples/typereaders/typereader.cs b/docs/guides/commands/samples/typereaders/typereader.cs
index a2a4627d2..28611872c 100644
--- a/docs/guides/commands/samples/typereaders/typereader.cs
+++ b/docs/guides/commands/samples/typereaders/typereader.cs
@@ -1,5 +1,6 @@
-// Note: This example is obsolete, a boolean type reader is bundled 
-// with Discord.Commands
+// Please note that the library already supports type reading
+// primitive types such as bool. This example is merely used
+// to demonstrate how one could write a simple TypeReader.
 using Discord;
 using Discord.Commands;