Add some more documentation

3 files changed, 100 insertions, 22 deletions

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);
     /// });