Add some more documentation

11 files changed, 129 insertions, 38 deletions

diff --git a/src/builder.rs b/src/builder.rs
index ccaefb9..f7c9f49 100644
--- a/src/builder.rs
+++ b/src/builder.rs
@@ -30,7 +30,11 @@ use ::model::{
 /// Create an invite with a max age of 3600 seconds and 10 max uses:
 ///
 /// ```rust,ignore
-/// // assuming a `client` has been bound
+/// use serenity::Client;
+/// use std::env;
+///
+/// let mut client = Client::login_bot(&env::var("DISCORD_BOT_TOKEN").unwrap());
+///
 /// client.on_message(|context, message| {
 ///     if message.content == "!invite" {
 ///         let invite = context.create_invite(message.channel_id, |i| i
diff --git a/src/client/connection.rs b/src/client/connection.rs
index 2b70518..cb3501b 100644
--- a/src/client/connection.rs
+++ b/src/client/connection.rs
@@ -95,11 +95,31 @@ impl Display for ConnectionError {
 ///
 /// **Note**: User accounts can not shard. Use [`Client::start`].
 ///
+/// # Stand-alone connections
+///
+/// You may instantiate a connection yourself if you need to, which is
+/// completely decoupled from the client. For most use cases, you will not need
+/// to do this, and you can leave the client to do it.
+///
+/// This can be done by passing in the required parameters to [`new`]. You can
+/// then manually handle the connection yourself and receive events via
+/// [`receive`].
+///
+/// **Note**: You _really_ do not need to do this. Just call one of the
+/// appropriate methods on the [`Client`].
+///
+/// # Examples
+///
+/// See the documentation for [`new`] on how to use this.
+///
+/// [`Client`]: struct.Client.html
 /// [`Client::start`]: struct.Client.html#method.start
-/// [`Client::start_auosharded`]: struct.Client.html#method.start_autosharded
+/// [`Client::start_autosharded`]: struct.Client.html#method.start_autosharded
 /// [`Client::start_shard`]: struct.Client.html#method.start_shard
 /// [`Client::start_shard_range`]: struct.Client.html#method.start_shard_range
 /// [`Client::start_shards`]: struct.Client.html#method.start_shards
+/// [`new`]: #method.new
+/// [`receive`]: #method.receive
 /// [docs]: https://discordapp.com/developers/docs/topics/gateway#sharding
 pub struct Connection {
     keepalive_channel: MpscSender<Status>,
@@ -113,6 +133,28 @@ pub struct Connection {
 }
 
 impl Connection {
+    /// Instantiates a new instance of a connection, bypassing the client.
+    ///
+    /// **Note**: You should likely never need to do this yourself.
+    ///
+    /// # Examples
+    ///
+    /// Instantiating a new Connection manually for a bot with no shards, and
+    /// then listening for events:
+    ///
+    /// ```rust,ignore
+    /// use serenity::client::{Connection, LoginType, http};
+    /// use std::env;
+    ///
+    /// let token = env::var("DISCORD_BOT_TOKEN").expect("Token in environment");
+    /// // retrieve the gateway response, which contains the URL to connect to
+    /// let gateway = http::get_gateway().expect("Valid gateway response").url;
+    /// let connection = Connection::new(&gateway, &token, None, LoginType::Bot)
+    ///     .expect("Working connection");
+    ///
+    /// // at this point, you can create a `loop`, and receive events and match
+    /// // their variants
+    /// ```
     pub fn new(base_url: &str,
                token: &str,
                shard_info: Option<[u8; 2]>,
diff --git a/src/client/context.rs b/src/client/context.rs
index 2fb0d22..7cd530a 100644
--- a/src/client/context.rs
+++ b/src/client/context.rs
@@ -90,11 +90,11 @@ impl Context {
     /// `0` days is equivilant to not removing any messages. Up to `7` days'
     /// worth of messages may be deleted.
     ///
-    /// Requires that you have the [Ban Members] permission.
+    /// **Note**: Requires that you have the [Ban Members] permission.
     ///
     /// # Examples
     ///
-    /// Ban a user that sent a message for `7` days:
+    /// Ban the user that sent a message for `7` days:
     ///
     /// ```rust,ignore
     /// // assuming you are in a context
@@ -130,6 +130,7 @@ impl Context {
     /// # Examples
     ///
     /// ```rust,ignore
+    /// // assuming you are in a context
     /// context.broadcast_typing(context.channel_id);
     /// ```
     pub fn broadcast_typing<C>(&self, channel_id: C) -> Result<()>
@@ -336,12 +337,20 @@ impl Context {
     ///
     /// # Examples
     ///
-    /// Deleting a message that was received by its Id:
+    /// Deleting every message that is received:
     ///
     /// ```rust,ignore
-    /// context.delete_message(context.message.id);
+    /// use serenity::Client;
+    /// use std::env;
+    ///
+    /// let client = Client::login_bot(&env::var("DISCORD_BOT_TOKEN").unwrap());
+    /// client.on_message(|context, message| {
+    ///     context.delete_message(message);
+    /// });
     /// ```
     ///
+    /// (in practice, please do not do this)
+    ///
     /// [`Message`]: ../model/struct.Message.html
     pub fn delete_message<C, M>(&self, channel_id: C, message_id: M)
         -> Result<()> where C: Into<ChannelId>, M: Into<MessageId> {
@@ -422,29 +431,42 @@ impl Context {
     /// There are three ways to send a direct message to someone, the first
     /// being an unrelated, although equally helpful method.
     ///
-    /// Sending a message via a [`User`]:
+    /// Sending a message via [`User::dm`]:
     ///
     /// ```rust,ignore
-    /// context.message.author.dm("Hello!");
+    /// // assuming you are in a context
+    /// let _ = context.message.author.dm("Hello!");
     /// ```
     ///
-    /// Sending a message to a PrivateChannel:
+    /// Sending a message to a `PrivateChannel`:
     ///
     /// ```rust,ignore
+    /// assuming you are in a context
     /// let private_channel = context.create_private_channel(context.message.author.id);
     ///
-    /// context.direct_message(private_channel, "Test!");
+    /// let _ = context.direct_message(private_channel, "Test!");
     /// ```
     ///
-    /// Sending a message to a PrivateChannel given its ID:
+    /// Sending a message to a `PrivateChannel` given its ID:
     ///
     /// ```rust,ignore
-    /// let private_channel = context.create_private_channel(context.message.author.id);
+    /// use serenity::Client;
+    /// use std::env;
+    ///
+    /// let mut client = Client::login_bot(&env::var("DISCORD_BOT_TOKEN").unwrap());
     ///
-    /// context.direct_message(private_channel.id, "Test!");
+    /// client.on_message(|context, message| {
+    ///     if message.content == "!pm-me" {
+    ///         let channel = context.create_private_channel(message.author.id)
+    ///             .unwrap();
+    ///
+    ///         let _ = channel.send_message("test!");
+    ///     }
+    /// });
     /// ```
     ///
-    /// [`User`]: ../model/struct.User.html
+    /// [`PrivateChannel`]: ../model/struct.PrivateChannel.html
+    /// [`User::dm`]: ../model/struct.User.html#method.dm
     pub fn direct_message<C>(&self, target_id: C, content: &str)
         -> Result<Message> where C: Into<ChannelId> {
         self.send_message(target_id.into(), content, "", false)
@@ -782,9 +804,9 @@ impl Context {
     ///
     /// Requires the [Kick Members] permission.
     ///
-    /// [Kick Members]: ../model/permissions/constant.KICK_MEMBERS.html
     /// [`Guild`]: ../model/struct.Guild.html
     /// [`Member`]: ../model/struct.Member.html
+    /// [Kick Members]: ../model/permissions/constant.KICK_MEMBERS.html
     pub fn kick_member<G, U>(&self, guild_id: G, user_id: U) -> Result<()>
         where G: Into<GuildId>, U: Into<UserId> {
         http::kick_member(guild_id.into().0, user_id.into().0)
@@ -859,15 +881,16 @@ impl Context {
     /// Sends a message with just the given message content in the channel that
     /// a message was received from.
     ///
-    /// **Note**: This will only work when a Message is received.
+    /// **Note**: This will only work when a [`Message`] is received.
     ///
     /// # Errors
     ///
     /// Returns a [`ClientError::NoChannelId`] when there is no [`ChannelId`]
     /// directly available.
     ///
-    /// [`ChannelId`]: ../models/struct.ChannelId.html
+    /// [`ChannelId`]: ../../models/struct.ChannelId.html
     /// [`ClientError::NoChannelId`]: ../enum.ClientError.html#NoChannelId
+    /// [`Message`]: ../model/struct.Message.html
     pub fn say(&self, text: &str) -> Result<Message> {
         if let Some(channel_id) = self.channel_id {
             self.send_message(channel_id, text, "", false)
@@ -905,6 +928,7 @@ impl Context {
     /// # Example
     ///
     /// ```rust,ignore
+    /// // assuming you are in a context
     /// let _ = context.send_message(message.channel_id, "Hello!", "", false);
     /// ```
     ///
@@ -959,7 +983,7 @@ impl Context {
 
     /// This is an alias of [`remove_ban`].
     ///
-    /// [`remove_ban`]: #method.remove_ban
+    /// [`#method.remove_ban`]: #method.remove_ban
     pub fn unban<G, U>(&self, guild_id: G, user_id: U) -> Result<()>
         where G: Into<GuildId>, U: Into<UserId> {
         self.remove_ban(guild_id.into().0, user_id.into().0)
diff --git a/src/client/mod.rs b/src/client/mod.rs
index c235177..95af69f 100644
--- a/src/client/mod.rs
+++ b/src/client/mod.rs
@@ -18,7 +18,7 @@
 //! ```rust,ignore
 //! use serenity::Client;
 //!
-//! let client = Client::login_bot("my token here");
+//! let mut client = Client::login_bot("my token here");
 //!
 //! client.on_message(|context, message| {
 //!     if message.content == "!ping" {
@@ -43,11 +43,11 @@ mod login_type;
 
 pub use self::connection::{Connection, ConnectionError};
 pub use self::context::Context;
+pub use self::login_type::LoginType;
 
 use hyper::status::StatusCode;
 use self::dispatch::dispatch;
 use self::event_store::EventStore;
-use self::login_type::LoginType;
 use serde_json::builder::ObjectBuilder;
 use std::collections::{BTreeMap, HashMap};
 use std::sync::{Arc, Mutex};
@@ -97,11 +97,13 @@ lazy_static! {
 /// use serenity::client::ClientError;
 /// use serenity::Error;
 ///
+/// // assuming you are in a context and a `guild_id` has been bound
+///
 /// match context.ban_user(context.guild_id, context.message.author, 8) {
 ///     Ok(()) => {
 ///         // Ban successful.
 ///     },
-///     Err(Error::Client(ClientError::DeleteMessageDaysAmount(amount)) => {
+///     Err(Error::Client(ClientError::DeleteMessageDaysAmount(amount))) => {
 ///         println!("Tried deleting {} days' worth of messages", amount);
 ///     },
 ///     Err(why) => {
@@ -352,7 +354,12 @@ impl Client {
     /// For a bot using a total of 10 shards, initialize shards 4 through 7:
     ///
     /// ```rust,ignore
-    /// // assumes a `client` has already been initialized
+    /// use serenity::Client;
+    /// use std::env;
+    ///
+    /// let mut client = Client::login_bot(&env::var("DISCORD_BOT_TOKEN")
+    ///     .unwrap());
+    ///
     /// let _ = client.start_shard_range([4, 7], 10);
     /// ```
     ///
@@ -718,7 +725,12 @@ impl Client {
     /// Print the [current user][`CurrentUser`]'s name on ready:
     ///
     /// ```rust,ignore
-    /// // assuming a `client` has been bound
+    /// use serenity::Client;
+    /// use std::env;
+    ///
+    /// let mut client = Client::login_bot(&env::var("DISCORD_BOT_TOKEN")
+    ///     .unwrap());
+    ///
     /// client.on_ready(|_context, ready| {
     ///     println!("{} is connected", ready.user.name);
     /// });
diff --git a/src/lib.rs b/src/lib.rs
index 92d27f8..7c0c321 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -44,13 +44,13 @@
 //! extern crate serenity;
 //!
 //! use serenity::Client;
+//! use std::env;
 //!
 //! fn main() {
 //!     // Login with a bot token from the environment
-//!     let client = Client::login_bot(env::var("DISCORD_TOKEN").expect("token"));
+//!     let mut client = Client::login_bot(&env::var("DISCORD_TOKEN").expect("token"));
 //!     client.with_framework(|f| f
-//!         .configure(|c| c.prefix("~")) // set the bot's prefix to "~"
-//!         .prefix("~")
+//!         .configure(|c| c.prefix("~")) // set the bot's prefix to '~'
 //!         .on("ping", |_context, message| drop(message.reply("Pong!"))));
 //!
 //!     let _ = client.start(); // start listening for events by starting a connection
diff --git a/src/model/guild.rs b/src/model/guild.rs
index 9b4bee1..a72a187 100644
--- a/src/model/guild.rs
+++ b/src/model/guild.rs
@@ -212,7 +212,9 @@ impl LiveGuild {
     /// # Examples
     ///
     /// ```rust,ignore
-    /// use serenity::models::ChannelType;
+    /// use serenity::model::ChannelType;
+    ///
+    /// // assuming a `guild` has already been bound
     ///
     /// let _ = guild.create_channel("my-test-channel", ChannelType::Text);
     /// ```
@@ -241,13 +243,11 @@ impl LiveGuild {
         http::create_channel(self.id.0, map)
     }
 
-    /// Creates a new [`Role`] in the guild with the data set,
-    /// if any.
+    /// Creates a new [`Role`] in the guild with the data set, if any.
     ///
     /// See the documentation for [`Context::create_role`] on how to use this.
     ///
-    /// **Note**: Requires the
-    /// [Manage Roles] permission.
+    /// **Note**: Requires the [Manage Roles] permission.
     ///
     /// # Errors
     ///
@@ -812,6 +812,7 @@ impl fmt::Display for Member {
     /// // assumes a `member` has already been bound
     /// println!("{} is a member!", member);
     /// ```
+    ///
     // This is in the format of `<@USER_ID>`.
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
         fmt::Display::fmt(&self.user.mention(), f)
diff --git a/src/model/permissions.rs b/src/model/permissions.rs
index 7097899..d9eb364 100644
--- a/src/model/permissions.rs
+++ b/src/model/permissions.rs
@@ -61,7 +61,7 @@ use ::prelude_internal::*;
 /// setting this to `false`, via:
 ///
 /// ```rust,ignore
-/// use serenity::models::permissions;
+/// use serenity::model::permissions;
 ///
 /// permissions::general().toggle(permissions::SEND_TTS_MESSAGES);
 /// ```
diff --git a/src/model/user.rs b/src/model/user.rs
index fc21ea5..b0c82cf 100644
--- a/src/model/user.rs
+++ b/src/model/user.rs
@@ -80,7 +80,7 @@ impl User {
     /// Check if a guild has a [`Role`] by Id:
     ///
     /// ```rust,ignore
-    /// // Assumes a 'guild' and `role_id` have already been defined
+    /// // Assumes a 'guild' and `role_id` have already been bound
     /// context.message.author.has_role(guild, role_id);
     /// ```
     ///
diff --git a/src/utils/colour.rs b/src/utils/colour.rs
index 7bb7bfd..b9a3bf5 100644
--- a/src/utils/colour.rs
+++ b/src/utils/colour.rs
@@ -17,7 +17,7 @@ macro_rules! colour {
 /// as the API works with an integer value instead of an RGB value.
 ///
 /// Instances can be created by using the struct's associated functions. These
-/// produce values equivilant to those found in the official client's colour
+/// produce presets equivilant to those found in the official client's colour
 /// picker.
 ///
 /// # Examples
@@ -36,12 +36,14 @@ macro_rules! colour {
 /// println!("The green component is: {}", green);
 /// ```
 ///
-/// Creating an instance with the [`dark_teal`] value:
+/// Creating an instance with the [`dark_teal`] presets:
 ///
 /// ```rust,ignore
 /// use serenity::utils::Colour;
 ///
 /// let colour = Colour::dark_teal();
+///
+/// assert_eq!(colour.get_tuple(), (17, 128, 106));
 /// ```
 ///
 /// [`Role`]: ../model/struct.Role.html
diff --git a/src/utils/message_builder.rs b/src/utils/message_builder.rs
index 252d068..7ba7717 100644
--- a/src/utils/message_builder.rs
+++ b/src/utils/message_builder.rs
@@ -14,10 +14,12 @@ use ::model::{ChannelId, Emoji, Mentionable, RoleId, UserId};
 /// ```rust,ignore
 /// use serenity::utils::MessageBuilder;
 ///
+/// // assuming an `emoji` and `user` have already been bound
+///
 /// let content = MessageBuilder::new()
 ///     .push("You sent a message, ")
 ///     .mention(user)
-///     .push("! ");
+///     .push("! ")
 ///     .mention(emoji)
 ///     .build();
 /// ```
diff --git a/src/utils/mod.rs b/src/utils/mod.rs
index 3ad6303..e6d2b4c 100644
--- a/src/utils/mod.rs
+++ b/src/utils/mod.rs
@@ -83,10 +83,12 @@ macro_rules! request {
 /// # Examples
 /// Retrieving the code from the URL `https://discord.gg/0cDvIgU2voY8RSYL`:
 ///
-/// ```rust
+/// ```rust,ignore
 /// use serenity::utils;
 ///
-/// assert!(utils::parse_invite("https://discord.gg/0cDvIgU2voY8RSYL") == "0cDvIgU2voY8RSYL");
+/// let url = "https://discord.gg/0cDvIgU2voY8RSYL";
+///
+/// assert!(utils::parse_invite(url) == "0cDvIgU2voY8RSYL");
 /// ```
 ///
 /// [`RichInvite`]: ../model/struct.RichInvite.html
@@ -117,6 +119,8 @@ pub fn parse_invite(code: &str) -> &str {
 ///     Ok(image) => image,
 ///     Err(why) => {
 ///         // properly handle the error
+///
+///         return;
 ///     },
 /// };
 /// ```