Add documentation for examples

The examples include a README located in `examples/README.md`, which
contains instructions for running these examples.

They act as a simple form of tutorial to the library, without getting
into too many details.

2 files changed, 73 insertions, 13 deletions

diff --git a/examples/06_command_framework/Cargo.toml b/examples/06_command_framework/Cargo.toml
index fa93475..26cfca9 100644
--- a/examples/06_command_framework/Cargo.toml
+++ b/examples/06_command_framework/Cargo.toml
@@ -5,3 +5,4 @@ authors = ["my name <[email protected]>"]
 
 [dependencies]
 serenity = { git = "https://github.com/zeyla/serenity.rs.git" }
+features = ["framework", "methods"]
diff --git a/examples/06_command_framework/src/main.rs b/examples/06_command_framework/src/main.rs
index 95d832c..b399dff 100644
--- a/examples/06_command_framework/src/main.rs
+++ b/examples/06_command_framework/src/main.rs
@@ -30,18 +30,34 @@ fn main() {
     // "~about"
     // "~emoji cat"
     // "~emoji dog"
+    // "~multiply"
     // "~ping"
-    // "~some complex command"
+    // "~some long command"
     client.with_framework(|f| f
+        // Configures the client, allowing for options to mutate how the
+        // framework functions.
+        //
+        // Refer to the documentation for
+        // `serenity::ext::framework::Configuration` for all available
+        // configurations.
         .configure(|c| c
             .allow_whitespace(true)
             .on_mention(true)
             .prefix("~"))
+        // Set a function to be called prior to each command execution. This
+        // provides the context of the command, the message that was received,
+        // and the full name of the command that will be called.
+        //
+        // You can not use this to determine whether a command should be
+        // executed. Instead, `set_check` is provided to give you this
+        // functionality.
         .before(|_context, message, command_name| {
             println!("Got command '{}' by user '{}'",
                      command_name,
                      message.author.name);
         })
+        // Very similar to `before`, except this will be called directly _after_
+        // command execution.
         .after(|_context, _message, command_name| {
             println!("Processed command '{}'", command_name)
         })
@@ -50,39 +66,82 @@ fn main() {
         .on("emoji cat", cat_command)
         .on("emoji dog", dog_command)
         .on("multiply", multiply)
-        .on("some complex command", some_complex_command)
-        // Commands can be in closure-form as well
+        .on("some long command", some_long_command)
+        // Commands can be in closure-form as well.
+        //
+        // This is not recommended though, as any closure larger than a couple
+        // lines will look ugly.
         .on("about", |context, _message, _args| drop(context.say("A test bot"))));
 
-    let _ = client.start();
+    if let Err(why) = client.start() {
+        println!("Client error: {:?}", why);
+    }
 }
 
+// Commands can be created via the `command!` macro, to avoid manually typing
+// type annotations.
+//
+// This may bring more features available for commands in the future. See the
+// "multiply" command below for some of the power that the `command!` macro can
+// bring.
 command!(cat_command(context, _msg, _arg) {
-    let _ = context.say(":cat:");
+    if let Err(why) = context.say(":cat:") {
+        println!("Eror sending message: {:?}", why);
+    }
 });
 
 fn dog_command(context: &Context, _msg: &Message, _args: Vec<String>) {
-    let _ = context.say(":dog:");
+    if let Err(why) = context.say(":dog:") {
+        println!("Error sending message: {:?}", why);
+    }
 }
 
-// `Message::reply` is only compiled if the `methods` feature flag is enabled.
 fn ping_command(_context: &Context, message: &Message, _args: Vec<String>) {
-    let _ = message.reply("Pong!");
+    if let Err(why) = message.reply("Pong!") {
+        println!("Error sending reply: {:?}", why);
+    }
 }
 
+// A function which acts as a "check", to determine whether to call a command.
+//
+// In this case, this command checks to ensure you are the owner of the message
+// in order for the command to be executed. If the check fails, the command is
+// not called.
 fn owner_check(_context: &Context, message: &Message) -> bool {
     // Replace 7 with your ID
     message.author.id == 7
 }
 
-fn some_complex_command(context: &Context, _msg: &Message, args: Vec<String>) {
-    let _ = context.say(&format!("Arguments: {:?}", args));
+fn some_long_command(context: &Context, _msg: &Message, args: Vec<String>) {
+    if let Err(why) = context.say(&format!("Arguments: {:?}", args)) {
+        println!("Error sending message: {:?}", why);
+    }
 }
 
+// Using the `command!` macro, commands can be created with a certain type of
+// "dynamic" type checking. This is a method of requiring that the arguments
+// given match the required type, and maps those arguments to the specified
+// bindings.
+//
+// For example, the following will be correctly parsed by the macro:
+//
+// `~multiply 3.7 4.3`
+//
+// However, the following will not, as the second argument can not be an f64:
+//
+// `~multiply 3.7 four`
+//
+// Since the argument can't be converted, the command returns early.
+//
+// Additionally, if not enough arguments are given (e.g. `~multiply 3`), then
+// the command will return early. If additional arguments are provided, they
+// will be ignored.
+//
+// Argument type overloading is currently not supported.
 command!(multiply(context, _message, args, first: f64, second: f64) {
     let res = first * second;
 
-    let _ = context.say(&res.to_string());
-
-    println!("{:?}", args);
+    if let Err(why) = context.say(&res.to_string()) {
+        println!("Err sending product of {} and {}: {:?}", first, second, why);
+    }
 });