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.

1 files changed, 29 insertions, 2 deletions

diff --git a/examples/01_basic_ping_bot/src/main.rs b/examples/01_basic_ping_bot/src/main.rs
index 8db4614..e00263b 100644
--- a/examples/01_basic_ping_bot/src/main.rs
+++ b/examples/01_basic_ping_bot/src/main.rs
@@ -7,17 +7,44 @@ fn main() {
     // Configure the client with your Discord bot token in the environment.
     let token = env::var("DISCORD_TOKEN")
         .expect("Expected a token in the environment");
+
+    // Create a new instance of the Client, logging in as a bot. This will
+    // automatically prepend your bot token with "Bot ", which is a requirement
+    // by Discord for bot users.
     let mut client = Client::login_bot(&token);
 
+    // Set a handler for the `on_message` event - so that whenever a new message
+    // is received - the closure (or function) passed will be called.
+    //
+    // Event handlers are dispatched through multi-threading, and so multiple
+    // of a single event can be dispatched simultaneously.
     client.on_message(|context, message| {
         if message.content == "!ping" {
-            let _ = context.say("Pong!");
+            // Sending a message can fail, due to a network error, an
+            // authentication error, or lack of permissions to post in the
+            // channel, so log to stdout when some error happens, with a
+            // description of it.
+            if let Err(why) = context.say("Pong!") {
+                println!("Error sending message: {:?}", why);
+            }
         }
     });
 
+    // Set a handler to be called on the `on_ready` event. This is called when a
+    // shard is booted, and a READY payload is sent by Discord. This payload
+    // contains data like the current user's guild Ids, current user data,
+    // relationships, and more.
+    //
+    // In this case, just print what the current user's username is.
     client.on_ready(|_context, ready| {
         println!("{} is connected!", ready.user.name);
     });
 
-    let _ = client.start();
+    // Finally, start a single shard, and start listening to events.
+    //
+    // Shards will automatically attempt to reconnect, and will perform
+    // exponential backoff until it reconnects.
+    if let Err(why) = client.start() {
+        println!("Client error: {:?}", why);
+    }
 }