From 2473619e63f7c7660c7a479116dc14f1c45d6fa0 Mon Sep 17 00:00:00 2001
From: Still Hsu <341464@gmail.com>
Date: Sun, 17 Mar 2019 02:49:53 +0800
Subject: [PATCH] docs: Clarify command samples  (#1257)

* Clarify command samples by adding additional notes about each methods

* Add additional notes for the Program class

* Change wording on token read

* Change prefix sample to match referenced example

Co-Authored-By: Still34 <341464@gmail.com>
---
 .../Modules/PublicModule.cs                    |  1 +
 samples/02_commands_framework/Program.cs       |  4 +++-
 .../Services/CommandHandlingService.cs         | 18 +++++++++++++++---
 3 files changed, 19 insertions(+), 4 deletions(-)

diff --git a/samples/02_commands_framework/Modules/PublicModule.cs b/samples/02_commands_framework/Modules/PublicModule.cs
index 8d55d8ba8..b9263649f 100644
--- a/samples/02_commands_framework/Modules/PublicModule.cs
+++ b/samples/02_commands_framework/Modules/PublicModule.cs
@@ -60,6 +60,7 @@ namespace _02_commands_framework.Modules
         public Task ListAsync(params string[] objects)
             => ReplyAsync("You listed: " + string.Join("; ", objects));
 
+        // Setting a custom ErrorMessage property will help clarify the precondition error
         [Command("guild_only")]
         [RequireContext(ContextType.Guild, ErrorMessage = "Sorry, this command must be ran from within a server, not a DM!")]
         public Task GuildOnlyCommand()
diff --git a/samples/02_commands_framework/Program.cs b/samples/02_commands_framework/Program.cs
index 76c11f9f0..ccbc8e165 100644
--- a/samples/02_commands_framework/Program.cs
+++ b/samples/02_commands_framework/Program.cs
@@ -37,10 +37,12 @@ namespace _02_commands_framework
                 client.Log += LogAsync;
                 services.GetRequiredService<CommandService>().Log += LogAsync;
 
-                // Tokens should be considered secret data, and never hard-coded.
+                // Tokens should be considered secret data and never hard-coded.
+                // We can read from the environment variable to avoid hardcoding.
                 await client.LoginAsync(TokenType.Bot, Environment.GetEnvironmentVariable("token"));
                 await client.StartAsync();
 
+                // Here we initialize the logic required to register our commands.
                 await services.GetRequiredService<CommandHandlingService>().InitializeAsync();
 
                 await Task.Delay(-1);
diff --git a/samples/02_commands_framework/Services/CommandHandlingService.cs b/samples/02_commands_framework/Services/CommandHandlingService.cs
index d29be9201..5ec496f78 100644
--- a/samples/02_commands_framework/Services/CommandHandlingService.cs
+++ b/samples/02_commands_framework/Services/CommandHandlingService.cs
@@ -20,12 +20,16 @@ namespace _02_commands_framework.Services
             _discord = services.GetRequiredService<DiscordSocketClient>();
             _services = services;
 
+            // Hook CommandExecuted to handle post-command-execution logic.
             _commands.CommandExecuted += CommandExecutedAsync;
+            // Hook MessageReceived so we can process each message to see
+            // if it qualifies as a command.
             _discord.MessageReceived += MessageReceivedAsync;
         }
 
         public async Task InitializeAsync()
         {
+            // Register modules that are public and inherit ModuleBase<T>.
             await _commands.AddModulesAsync(Assembly.GetEntryAssembly(), _services);
         }
 
@@ -37,10 +41,18 @@ namespace _02_commands_framework.Services
 
             // This value holds the offset where the prefix ends
             var argPos = 0;
+            // Perform prefix check. You may want to replace this with
+            // (!message.HasCharPrefix('!', ref argPos))
+            // for a more traditional command format like !help.
             if (!message.HasMentionPrefix(_discord.CurrentUser, ref argPos)) return;
 
             var context = new SocketCommandContext(_discord, message);
-            await _commands.ExecuteAsync(context, argPos, _services); // we will handle the result in CommandExecutedAsync
+            // Perform the execution of the command. In this method,
+            // the command service will perform precondition and parsing check
+            // then execute the command if one is matched.
+            await _commands.ExecuteAsync(context, argPos, _services); 
+            // Note that normally a result will be returned by this format, but here
+            // we will handle the result in CommandExecutedAsync,
         }
 
         public async Task CommandExecutedAsync(Optional<CommandInfo> command, ICommandContext context, IResult result)
@@ -49,12 +61,12 @@ namespace _02_commands_framework.Services
             if (!command.IsSpecified)
                 return;
 
-            // the command was succesful, we don't care about this result, unless we want to log that a command succeeded.
+            // the command was successful, we don't care about this result, unless we want to log that a command succeeded.
             if (result.IsSuccess)
                 return;
 
             // the command failed, let's notify the user that something happened.
-            await context.Channel.SendMessageAsync($"error: {result.ToString()}");
+            await context.Channel.SendMessageAsync($"error: {result}");
         }
     }
 }