Add Context, REST, and model documentation

Add documentation for Context methods, as well as brief documentation
for REST functions and model definitions.

4 files changed, 205 insertions, 4 deletions

diff --git a/src/client/context.rs b/src/client/context.rs
index ddfe64d..26ed22c 100644
--- a/src/client/context.rs
+++ b/src/client/context.rs
@@ -462,6 +462,20 @@ impl Context {
                               reaction_type.into())
     }
 
+    /// Creates a [`Role`] in guild with given Id. Second argument is a
+    /// closure, and you can use it to automatically configure role.
+    ///
+    /// # Examples
+    ///
+    /// This creates a role which can be mentioned, with name 'test':
+    ///
+    /// ```rust,ignore
+    /// let role = context.create_role(guild_id, |r| r
+    ///     .hoist(true)
+    ///     .name("role"));
+    /// ```
+    ///
+    /// [`Role`]: ../model/struct.Role.html
     pub fn create_role<F, G>(&self, guild_id: G, f: F) -> Result<Role>
         where F: FnOnce(EditRole) -> EditRole, G: Into<GuildId> {
         let id = guild_id.into().0;
@@ -508,6 +522,7 @@ impl Context {
         rest::delete_guild(guild_id.into().0)
     }
 
+    /// Deletes an integration by Id from a server which Id was given.
     pub fn delete_integration<G, I>(&self, guild_id: G, integration_id: I)
         -> Result<()> where G: Into<GuildId>, I: Into<IntegrationId> {
         rest::delete_guild_integration(guild_id.into().0,
@@ -557,6 +572,12 @@ impl Context {
         rest::delete_message(channel_id.into().0, message_id.into().0)
     }
 
+    /// Deletes all messages by Ids from the given vector in the given channel.
+    ///
+    /// The minimum amount of messages is 2 and the maximum amount is 100.
+    ///
+    /// **Note**: This uses bulk delete endpoint which is not available
+    /// for user accounts.
     pub fn delete_messages<C>(&self, channel_id: C, message_ids: &[MessageId])
         -> Result<()> where C: Into<ChannelId> {
         if self.login_type == LoginType::User {
@@ -574,6 +595,7 @@ impl Context {
         rest::delete_messages(channel_id.into().0, map)
     }
 
+    /// Deletes a profile note from a user.
     pub fn delete_note<U: Into<UserId>>(&self, user_id: U) -> Result<()> {
         let map = ObjectBuilder::new()
             .insert("note", "")
@@ -582,6 +604,8 @@ impl Context {
         rest::edit_note(user_id.into().0, map)
     }
 
+    /// Deletes all permission overrides in a channel from a member or
+    /// a role.
     pub fn delete_permission<C>(&self,
                                 channel_id: C,
                                 permission_type: PermissionOverwriteType)
@@ -618,6 +642,7 @@ impl Context {
                               reaction_type.into())
     }
 
+    /// Deletes a role by Id from the given guild.
     pub fn delete_role<G, R>(&self, guild_id: G, role_id: R) -> Result<()>
         where G: Into<GuildId>, R: Into<RoleId> {
         rest::delete_role(guild_id.into().0, role_id.into().0)
@@ -672,6 +697,18 @@ impl Context {
         self.send_message(target_id.into(), |m| m.content(content))
     }
 
+    /// Allows to configure channel options like position, name, etc.
+    /// You can see available methods in `EditChannel` docs.
+    ///
+    /// # Examples
+    ///
+    /// Change a voice channel's name and bitrate:
+    ///
+    /// ```rust,ignore
+    /// context.edit_channel(channel_id, |c| c
+    ///     .name("test")
+    ///     .bitrate(71));
+    /// ```
     pub fn edit_channel<C, F>(&self, channel_id: C, f: F)
         -> Result<GuildChannel> where C: Into<ChannelId>,
                                        F: FnOnce(EditChannel) -> EditChannel {
@@ -705,6 +742,7 @@ impl Context {
         rest::edit_channel(channel_id.0, edited)
     }
 
+    /// Allows to rename specific emoji by Id.
     pub fn edit_emoji<E, G>(&self, guild_id: G, emoji_id: E, name: &str)
         -> Result<Emoji> where E: Into<EmojiId>, G: Into<GuildId> {
         let map = ObjectBuilder::new()
@@ -714,6 +752,29 @@ impl Context {
         rest::edit_emoji(guild_id.into().0, emoji_id.into().0, map)
     }
 
+    /// Allows to configure specific guild options like icon, AFK channel, etc.
+    ///
+    /// You can see available methods in `EditGuild` docs.
+    ///
+    /// # Examples
+    ///
+    /// Change a server's icon using a file name "icon.png":
+    ///
+    /// ```rust,ignore
+    /// use serenity::utils;
+    ///
+    /// // We are using read_image helper function from utils.
+    /// let base64_icon = match utils::read_image("./icon.png") {
+    ///     Ok(base64_icon) => base64_icon,
+    ///     Err(why) => {
+    ///         println!("Error reading image: {:?}", why);
+    ///         return;
+    ///     },
+    /// };
+    ///
+    /// context.edit_guild(guild_id, |g|
+    ///     g.icon(base64_icon));
+    /// ```
     pub fn edit_guild<F, G>(&self, guild_id: G, f: F) -> Result<PartialGuild>
         where F: FnOnce(EditGuild) -> EditGuild, G: Into<GuildId> {
         let map = f(EditGuild::default()).0.build();
@@ -721,6 +782,20 @@ impl Context {
         rest::edit_guild(guild_id.into().0, map)
     }
 
+    /// Allows to do specific things with members of a server
+    /// like mute, change nickname, etc.
+    /// Full list of methods is available at `EditMember` docs.
+    ///
+    /// # Examples
+    ///
+    /// Mute a member and set their roles to just one role with
+    /// the predefined Id.
+    ///
+    /// ```rust,ignore
+    /// context.edit_member(guild_id, user_id, |m| m
+    ///     .mute(true)
+    ///     .roles(&vec![role_id]));
+    /// ```
     pub fn edit_member<F, G, U>(&self, guild_id: G, user_id: U, f: F)
         -> Result<()> where F: FnOnce(EditMember) -> EditMember,
                             G: Into<GuildId>,
@@ -744,6 +819,16 @@ impl Context {
         rest::edit_nickname(guild_id.into().0, new_nickname)
     }
 
+    /// Allows to edit info of a account we're connected to.
+    ///
+    /// # Examples
+    ///
+    /// Change our username:
+    ///
+    /// ```rust,ignore
+    /// context.edit_member(|p|
+    ///     p.username("meew zero"));
+    /// ```
     pub fn edit_profile<F: FnOnce(EditProfile) -> EditProfile>(&mut self, f: F)
         -> Result<CurrentUser> {
         let user = try!(rest::get_current_user());
@@ -761,6 +846,15 @@ impl Context {
         rest::edit_profile(edited)
     }
 
+    /// Allows to edit role options like colour, permissions etc.
+    ///
+    /// # Examples
+    ///
+    /// Make a role hoisted:
+    /// ```rust,ignore
+    /// context.edit_role(, guild_id, role_id, |r|
+    ///     r.hoist(true));
+    /// ```
     pub fn edit_role<F, G, R>(&self, guild_id: G, role_id: R, f: F)
         -> Result<Role> where F: FnOnce(EditRole) -> EditRole,
                               G: Into<GuildId>,
@@ -809,6 +903,7 @@ impl Context {
         rest::edit_message(channel_id.into().0, message_id.into().0, map.build())
     }
 
+    /// Changes note of a user profile.
     pub fn edit_note<U: Into<UserId>>(&self, user_id: U, note: &str)
         -> Result<()> {
         let map = ObjectBuilder::new()
@@ -818,15 +913,18 @@ impl Context {
         rest::edit_note(user_id.into().0, map)
     }
 
+    /// Gets a vector of bans server has.
     pub fn get_bans<G: Into<GuildId>>(&self, guild_id: G) -> Result<Vec<Ban>> {
         rest::get_bans(guild_id.into().0)
     }
 
+    /// Gets all invites a channel has.
     pub fn get_channel_invites<C: Into<ChannelId>>(&self, channel_id: C)
         -> Result<Vec<RichInvite>> {
         rest::get_channel_invites(channel_id.into().0)
     }
 
+    /// Gets `Channel` by the given Id, checking cache first.
     pub fn get_channel<C>(&self, channel_id: C) -> Result<Channel>
         where C: Into<ChannelId> {
         let channel_id = channel_id.into();
@@ -840,6 +938,7 @@ impl Context {
         rest::get_channel(channel_id.0)
     }
 
+    /// Gets all channels of a guild with given Id, checking cache first.
     pub fn get_channels<G>(&self, guild_id: G)
         -> Result<HashMap<ChannelId, GuildChannel>> where G: Into<GuildId> {
         let guild_id = guild_id.into();
@@ -861,26 +960,32 @@ impl Context {
         Ok(channels)
     }
 
+    /// Gets [`Emoji`] by the given Id from a server.
     pub fn get_emoji<E, G>(&self, guild_id: G, emoji_id: E) -> Result<Emoji>
         where E: Into<EmojiId>, G: Into<GuildId> {
         rest::get_emoji(guild_id.into().0, emoji_id.into().0)
     }
 
+    /// Gets a vector of all [`Emojis`] a server has.
     pub fn get_emojis<G: Into<GuildId>>(&self, guild_id: G)
         -> Result<Vec<Emoji>> {
         rest::get_emojis(guild_id.into().0)
     }
 
+    /// Gets [`PartialGuild`] by the given Id.
     pub fn get_guild<G: Into<GuildId>>(&self, guild_id: G)
         -> Result<PartialGuild> {
         rest::get_guild(guild_id.into().0)
     }
 
+    /// Gets all [`RichInvite`]s a guild has.
     pub fn get_guild_invites<G>(&self, guild_id: G) -> Result<Vec<RichInvite>>
         where G: Into<GuildId> {
         rest::get_guild_invites(guild_id.into().0)
     }
 
+    /// Gives the amount of members that would be pruned with the
+    /// given days parameter right now.
     pub fn get_guild_prune_count<G>(&self, guild_id: G, days: u16)
         -> Result<GuildPrune> where G: Into<GuildId> {
         let map = ObjectBuilder::new()
@@ -890,21 +995,25 @@ impl Context {
         rest::get_guild_prune_count(guild_id.into().0, map)
     }
 
+    /// Gets all guilds we are connected to.
     pub fn get_guilds(&self) -> Result<Vec<GuildInfo>> {
         rest::get_guilds()
     }
 
+    /// Gets all [`Integration`]s of a guild by the given Id.
     pub fn get_integrations<G: Into<GuildId>>(&self, guild_id: G)
         -> Result<Vec<Integration>> {
         rest::get_guild_integrations(guild_id.into().0)
     }
 
+    /// Gets invite code information.
     pub fn get_invite(&self, invite: &str) -> Result<Invite> {
         let code = utils::parse_invite(invite);
 
         rest::get_invite(code)
     }
 
+    /// Gets `Member` of a specific server by Id, checking cache first.
     pub fn get_member<G, U>(&self, guild_id: G, user_id: U) -> Result<Member>
         where G: Into<GuildId>, U: Into<UserId> {
         let guild_id = guild_id.into();
@@ -942,6 +1051,15 @@ impl Context {
         rest::get_message(channel_id.into().0, message_id.into().0)
     }
 
+    /// Gets messages from a specific channel.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,ignore
+    /// let role = context.get_messages(channel_id, |g| g
+    ///     .before(20)
+    ///     .after(100)); // Maximum is 100.
+    /// ```
     pub fn get_messages<C, F>(&self, channel_id: C, f: F) -> Result<Vec<Message>>
         where C: Into<ChannelId>, F: FnOnce(GetMessages) -> GetMessages {
         let query = {
@@ -1024,11 +1142,13 @@ impl Context {
         rest::kick_member(guild_id.into().0, user_id.into().0)
     }
 
+    /// Leave a guild by the given Id.
     pub fn leave_guild<G: Into<GuildId>>(&self, guild_id: G)
         -> Result<PartialGuild> {
         rest::leave_guild(guild_id.into().0)
     }
 
+    /// Moves a member to a specific voice channel.
     pub fn move_member<C, G, U>(&self, guild_id: G, user_id: U, channel_id: C)
         -> Result<()> where C: Into<ChannelId>,
                             G: Into<ChannelId>,
@@ -1050,6 +1170,7 @@ impl Context {
         rest::get_pins(channel_id.into().0)
     }
 
+    /// Pins a message in the specified channel by the given Id.
     pub fn pin<C, M>(&self, channel_id: C, message_id: M) -> Result<()>
         where C: Into<ChannelId>, M: Into<MessageId> {
         rest::pin_message(channel_id.into().0, message_id.into().0)
@@ -1369,6 +1490,12 @@ impl Context {
             .set_presence(game, status, afk)
     }
 
+    /// Deletes an undefined amount of members from the given server
+    /// based on the amount of days they've been offline for.
+    ///
+    /// **Note**: This will trigger [`GuildMemberRemove`] events
+    ///
+    /// [`GuildMemberRemove`]: ../model/event/enum.Event.html#variant.GuildMemberRemove
     pub fn start_guild_prune<G>(&self, guild_id: G, days: u16)
         -> Result<GuildPrune> where G: Into<GuildId> {
         let map = ObjectBuilder::new()
@@ -1378,6 +1505,7 @@ impl Context {
         rest::start_guild_prune(guild_id.into().0, map)
     }
 
+    /// Starts integration synchronization by the given integration Id.
     pub fn start_integration_sync<G, I>(&self, guild_id: G, integration_id: I)
         -> Result<()> where G: Into<GuildId>, I: Into<IntegrationId> {
         rest::start_integration_sync(guild_id.into().0, integration_id.into().0)
@@ -1395,6 +1523,8 @@ impl Context {
         rest::remove_ban(guild_id.into().0, user_id.into().0)
     }
 
+
+    /// Unpins a message in the specified channel by the given Id.
     pub fn unpin<C, M>(&self, channel_id: C, message_id: M) -> Result<()>
         where C: Into<ChannelId>, M: Into<MessageId> {
         rest::unpin_message(channel_id.into().0, message_id.into().0)
diff --git a/src/client/rest/mod.rs b/src/client/rest/mod.rs
index 3387d5d..b6218cd 100644
--- a/src/client/rest/mod.rs
+++ b/src/client/rest/mod.rs
@@ -319,6 +319,7 @@ pub fn create_invite(channel_id: u64, map: Value)
     RichInvite::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Creates a permission override for a member or a role in a channel.
 pub fn create_permission(channel_id: u64, target_id: u64, map: Value)
     -> Result<()> {
     let body = try!(serde_json::to_string(&map));
@@ -330,6 +331,7 @@ pub fn create_permission(channel_id: u64, target_id: u64, map: Value)
                          target_id))
 }
 
+/// Creates a private channel with a user.
 pub fn create_private_channel(map: Value)
     -> Result<PrivateChannel> {
     let body = try!(serde_json::to_string(&map));
@@ -340,6 +342,7 @@ pub fn create_private_channel(map: Value)
     PrivateChannel::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Reacts to a message.
 pub fn create_reaction(channel_id: u64,
                        message_id: u64,
                        reaction_type: ReactionType)
@@ -352,6 +355,7 @@ pub fn create_reaction(channel_id: u64,
                          reaction_type.as_data()))
 }
 
+/// Creates a role.
 pub fn create_role(guild_id: u64) -> Result<Role> {
     let body = String::from("{}");
     let response = request!(Route::GuildsIdRoles(guild_id),
@@ -402,6 +406,7 @@ pub fn create_webhook(channel_id: u64, map: Value) -> Result<Webhook> {
     Webhook::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Deketes a private channel or a channel in a guild.
 pub fn delete_channel(channel_id: u64) -> Result<Channel> {
     let response = request!(Route::ChannelsId(channel_id),
                             delete,
@@ -411,6 +416,7 @@ pub fn delete_channel(channel_id: u64) -> Result<Channel> {
     Channel::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Deletes an emoji from a server.
 pub fn delete_emoji(guild_id: u64, emoji_id: u64) -> Result<()> {
     verify(204, request!(Route::GuildsIdEmojisId(guild_id),
                          delete,
@@ -419,6 +425,7 @@ pub fn delete_emoji(guild_id: u64, emoji_id: u64) -> Result<()> {
                          emoji_id))
 }
 
+/// Deletes a guild, only if connected account owns it.
 pub fn delete_guild(guild_id: u64) -> Result<PartialGuild> {
     let response = request!(Route::GuildsId(guild_id),
                             delete,
@@ -428,6 +435,7 @@ pub fn delete_guild(guild_id: u64) -> Result<PartialGuild> {
     PartialGuild::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Remvoes an integration from a guild.
 pub fn delete_guild_integration(guild_id: u64, integration_id: u64)
     -> Result<()> {
     verify(204, request!(Route::GuildsIdIntegrationsId(guild_id),
@@ -437,12 +445,15 @@ pub fn delete_guild_integration(guild_id: u64, integration_id: u64)
                          integration_id))
 }
 
+/// Deletes an invite by code.
 pub fn delete_invite(code: &str) -> Result<Invite> {
     let response = request!(Route::InvitesCode, delete, "/invite/{}", code);
 
     Invite::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Deletes a message if created by us or we have
+/// specific permissions.
 pub fn delete_message(channel_id: u64, message_id: u64)
     -> Result<()> {
     verify(204, request!(Route::ChannelsIdMessagesId(channel_id),
@@ -452,6 +463,7 @@ pub fn delete_message(channel_id: u64, message_id: u64)
                          message_id))
 }
 
+/// Deletes a bunch of messages, only works for bots.
 pub fn delete_messages(channel_id: u64, map: Value) -> Result<()> {
     let body = try!(serde_json::to_string(&map));
 
@@ -461,7 +473,7 @@ pub fn delete_messages(channel_id: u64, map: Value) -> Result<()> {
                          channel_id))
 }
 
-/// Delete all of the [`Reaction`]s associated with a [`Message`].
+/// Deletes all of the [`Reaction`]s associated with a [`Message`].
 ///
 /// # Examples
 ///
@@ -489,6 +501,7 @@ pub fn delete_message_reactions(channel_id: u64, message_id: u64)
                          message_id))
 }
 
+/// Deletes a permission override from a role or a member in a channel.
 pub fn delete_permission(channel_id: u64, target_id: u64)
     -> Result<()> {
     verify(204, request!(Route::ChannelsIdPermissionsOverwriteId(channel_id),
@@ -498,6 +511,8 @@ pub fn delete_permission(channel_id: u64, target_id: u64)
                          target_id))
 }
 
+/// Deletes a reaction from a message if owned by us or
+/// we have specific permissions.
 pub fn delete_reaction(channel_id: u64,
                        message_id: u64,
                        user_id: Option<u64>,
@@ -514,6 +529,7 @@ pub fn delete_reaction(channel_id: u64,
                          user))
 }
 
+/// Deletes a role from a server. Can't remove the default everyone role.
 pub fn delete_role(guild_id: u64, role_id: u64) -> Result<()> {
     verify(204, request!(Route::GuildsIdRolesId(guild_id),
                          delete,
@@ -529,7 +545,7 @@ pub fn delete_role(guild_id: u64, role_id: u64) -> Result<()> {
 ///
 /// # Examples
 ///
-/// Delete a webhook given its Id:
+/// Deletes a webhook given its Id:
 ///
 /// ```rust,no_run
 /// use serenity::client::{Client, rest};
@@ -554,7 +570,7 @@ pub fn delete_webhook(webhook_id: u64) -> Result<()> {
 ///
 /// # Examples
 ///
-/// Delete a webhook given its Id and unique token:
+/// Deletes a webhook given its Id and unique token:
 ///
 /// ```rust,no_run
 /// use serenity::client::rest;
@@ -572,6 +588,7 @@ pub fn delete_webhook_with_token(webhook_id: u64, token: &str) -> Result<()> {
         .map_err(Error::Hyper)))
 }
 
+/// Changes channel information.
 pub fn edit_channel(channel_id: u64, map: Value)
     -> Result<GuildChannel> {
     let body = try!(serde_json::to_string(&map));
@@ -583,6 +600,7 @@ pub fn edit_channel(channel_id: u64, map: Value)
     GuildChannel::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Changes emoji information.
 pub fn edit_emoji(guild_id: u64, emoji_id: u64, map: Value)
     -> Result<Emoji> {
     let body = try!(serde_json::to_string(&map));
@@ -595,6 +613,7 @@ pub fn edit_emoji(guild_id: u64, emoji_id: u64, map: Value)
     Emoji::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Changes guild information.
 pub fn edit_guild(guild_id: u64, map: Value) -> Result<PartialGuild> {
     let body = try!(serde_json::to_string(&map));
     let response = request!(Route::GuildsId(guild_id),
@@ -605,6 +624,7 @@ pub fn edit_guild(guild_id: u64, map: Value) -> Result<PartialGuild> {
     PartialGuild::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Does specific actions to a member.
 pub fn edit_member(guild_id: u64, user_id: u64, map: Value)
     -> Result<()> {
     let body = try!(serde_json::to_string(&map));
@@ -616,6 +636,7 @@ pub fn edit_member(guild_id: u64, user_id: u64, map: Value)
                          user_id))
 }
 
+/// Changes message content, only if owned by us.
 pub fn edit_message(channel_id: u64,
                     message_id: u64,
                     map: Value)
@@ -647,6 +668,7 @@ pub fn edit_nickname(guild_id: u64, new_nickname: Option<&str>)
     verify(200, response)
 }
 
+/// Changes a profile note.
 pub fn edit_note(user_id: u64, map: Value) -> Result<()> {
     let body = try!(serde_json::to_string(&map));
 
@@ -656,6 +678,7 @@ pub fn edit_note(user_id: u64, map: Value) -> Result<()> {
                          user_id))
 }
 
+/// Edits profile we're connected to.
 pub fn edit_profile(map: Value) -> Result<CurrentUser> {
     let body = try!(serde_json::to_string(&map));
     let response = request!(Route::UsersMe, patch(body), "/users/@me");
@@ -663,6 +686,7 @@ pub fn edit_profile(map: Value) -> Result<CurrentUser> {
     CurrentUser::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Changes a role in a guild.
 pub fn edit_role(guild_id: u64, role_id: u64, map: Value)
     -> Result<Role> {
     let body = try!(serde_json::to_string(&map));
@@ -824,12 +848,18 @@ pub fn execute_webhook(webhook_id: u64, token: &str, map: Value)
     Message::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets information about an oauth2 application we own.
+///
+/// **Note**: Only user accounts may use this endpoint.
 pub fn get_application_info() -> Result<CurrentApplicationInfo> {
     let response = request!(Route::None, get, "/oauth2/applications/@me");
 
     CurrentApplicationInfo::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets all oauth2 applications we've made.
+///
+/// **Note**: Only user accounts may use this endpoint.
 pub fn get_applications() -> Result<Vec<ApplicationInfo>> {
     let response = request!(Route::None, get, "/oauth2/applications");
     let decoded = try!(serde_json::from_reader(response));
@@ -837,6 +867,7 @@ pub fn get_applications() -> Result<Vec<ApplicationInfo>> {
     decode_array(decoded, ApplicationInfo::decode)
 }
 
+/// Gets all the users that are banned in specific guild.
 pub fn get_bans(guild_id: u64) -> Result<Vec<Ban>> {
     let response = request!(Route::GuildsIdBans(guild_id),
                             get,
@@ -846,12 +877,14 @@ pub fn get_bans(guild_id: u64) -> Result<Vec<Ban>> {
     decode_array(try!(serde_json::from_reader(response)), Ban::decode)
 }
 
+/// Gets current bot gateway.
 pub fn get_bot_gateway() -> Result<BotGateway> {
     let response = request!(Route::GatewayBot, get, "/gateway/bot");
 
     BotGateway::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets all invites for a channel.
 pub fn get_channel_invites(channel_id: u64)
     -> Result<Vec<RichInvite>> {
     let response = request!(Route::ChannelsIdInvites(channel_id),
@@ -890,6 +923,7 @@ pub fn get_channel_webhooks(channel_id: u64) -> Result<Vec<Webhook>> {
     decode_array(try!(serde_json::from_reader(response)), Webhook::decode)
 }
 
+/// Gets channel information.
 pub fn get_channel(channel_id: u64) -> Result<Channel> {
     let response = request!(Route::ChannelsId(channel_id),
                             get,
@@ -899,6 +933,7 @@ pub fn get_channel(channel_id: u64) -> Result<Channel> {
     Channel::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets all channels in a guild.
 pub fn get_channels(guild_id: u64) -> Result<Vec<GuildChannel>> {
     let response = request!(Route::ChannelsId(guild_id),
                             get,
@@ -909,18 +944,21 @@ pub fn get_channels(guild_id: u64) -> Result<Vec<GuildChannel>> {
                  GuildChannel::decode)
 }
 
+/// Gets information about the user we're connected with.
 pub fn get_current_user() -> Result<CurrentUser> {
     let response = request!(Route::UsersMe, get, "/users/@me");
 
     CurrentUser::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets current gateway.
 pub fn get_gateway() -> Result<Gateway> {
     let response = request!(Route::Gateway, get, "/gateway");
 
     Gateway::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets information about an emoji.
 pub fn get_emoji(guild_id: u64, emoji_id: u64) -> Result<Emoji> {
     let response = request!(Route::GuildsIdEmojisId(guild_id),
                             get,
@@ -931,6 +969,7 @@ pub fn get_emoji(guild_id: u64, emoji_id: u64) -> Result<Emoji> {
     Emoji::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets all emojis in a guild.
 pub fn get_emojis(guild_id: u64) -> Result<Vec<Emoji>> {
     let response = request!(Route::GuildsIdEmojis(guild_id),
                             get,
@@ -940,6 +979,7 @@ pub fn get_emojis(guild_id: u64) -> Result<Vec<Emoji>> {
     decode_array(try!(serde_json::from_reader(response)), Emoji::decode)
 }
 
+/// Gets guild information.
 pub fn get_guild(guild_id: u64) -> Result<PartialGuild> {
     let response = request!(Route::GuildsId(guild_id),
                             get,
@@ -949,6 +989,7 @@ pub fn get_guild(guild_id: u64) -> Result<PartialGuild> {
     PartialGuild::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets a guild embed information.
 pub fn get_guild_embed(guild_id: u64) -> Result<GuildEmbed> {
     let response = request!(Route::GuildsIdEmbed(guild_id),
                             get,
@@ -958,6 +999,7 @@ pub fn get_guild_embed(guild_id: u64) -> Result<GuildEmbed> {
     GuildEmbed::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets integrations that a guild has.
 pub fn get_guild_integrations(guild_id: u64) -> Result<Vec<Integration>> {
     let response = request!(Route::GuildsIdIntegrations(guild_id),
                             get,
@@ -967,6 +1009,7 @@ pub fn get_guild_integrations(guild_id: u64) -> Result<Vec<Integration>> {
     decode_array(try!(serde_json::from_reader(response)), Integration::decode)
 }
 
+/// Gets all invites to a guild.
 pub fn get_guild_invites(guild_id: u64) -> Result<Vec<RichInvite>> {
     let response = request!(Route::GuildsIdInvites(guild_id),
                             get,
@@ -977,6 +1020,7 @@ pub fn get_guild_invites(guild_id: u64) -> Result<Vec<RichInvite>> {
                  RichInvite::decode)
 }
 
+/// Gets the amount of users that can be pruned.
 pub fn get_guild_prune_count(guild_id: u64, map: Value)
     -> Result<GuildPrune> {
     let body = try!(serde_json::to_string(&map));
@@ -988,6 +1032,7 @@ pub fn get_guild_prune_count(guild_id: u64, map: Value)
     GuildPrune::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets regions that a guild can use, if a guild is VIP shows more regions :o
 pub fn get_guild_regions(guild_id: u64) -> Result<Vec<VoiceRegion>> {
     let response = request!(Route::GuildsIdRegions(guild_id),
                             get,
@@ -1024,6 +1069,7 @@ pub fn get_guild_webhooks(guild_id: u64) -> Result<Vec<Webhook>> {
     decode_array(try!(serde_json::from_reader(response)), Webhook::decode)
 }
 
+/// Gets all guilds we're connected to.
 pub fn get_guilds() -> Result<Vec<GuildInfo>> {
     let response = request!(Route::UsersMeGuilds,
                             get,
@@ -1032,6 +1078,7 @@ pub fn get_guilds() -> Result<Vec<GuildInfo>> {
     decode_array(try!(serde_json::from_reader(response)), GuildInfo::decode)
 }
 
+/// Gets information about a specific invite.
 pub fn get_invite(code: &str) -> Result<Invite> {
     let invite = ::utils::parse_invite(code);
     let response = request!(Route::InvitesCode, get, "/invite/{}", invite);
@@ -1039,6 +1086,7 @@ pub fn get_invite(code: &str) -> Result<Invite> {
     Invite::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets member of a guild.
 pub fn get_member(guild_id: u64, user_id: u64) -> Result<Member> {
     let response = request!(Route::GuildsIdMembersId(guild_id),
                             get,
@@ -1049,6 +1097,7 @@ pub fn get_member(guild_id: u64, user_id: u64) -> Result<Member> {
     Member::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets a message by an Id, bots only.
 pub fn get_message(channel_id: u64, message_id: u64)
     -> Result<Message> {
     let response = request!(Route::ChannelsIdMessagesId(channel_id),
@@ -1060,6 +1109,7 @@ pub fn get_message(channel_id: u64, message_id: u64)
     Message::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets X messages from a channel.
 pub fn get_messages(channel_id: u64, query: &str)
     -> Result<Vec<Message>> {
     let url = format!(api_concat!("/channels/{}/messages{}"),
@@ -1072,6 +1122,7 @@ pub fn get_messages(channel_id: u64, query: &str)
     decode_array(try!(serde_json::from_reader(response)), Message::decode)
 }
 
+/// Gets all pins of a channel.
 pub fn get_pins(channel_id: u64) -> Result<Vec<Message>> {
     let response = request!(Route::ChannelsIdPins(channel_id),
                             get,
@@ -1081,6 +1132,7 @@ pub fn get_pins(channel_id: u64) -> Result<Vec<Message>> {
     decode_array(try!(serde_json::from_reader(response)), Message::decode)
 }
 
+/// Gets user Ids based on their reaction to a message. This endpoint is dumb.
 pub fn get_reaction_users(channel_id: u64,
                           message_id: u64,
                           reaction_type: ReactionType,
@@ -1106,12 +1158,14 @@ pub fn get_reaction_users(channel_id: u64,
     decode_array(try!(serde_json::from_reader(response)), User::decode)
 }
 
+/// Gets a user by Id.
 pub fn get_user(user_id: u64) -> Result<CurrentUser> {
     let response = request!(Route::UsersId, get, "/users/{}", user_id);
 
     CurrentUser::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Gets our connections.
 pub fn get_user_connections() -> Result<Vec<UserConnection>> {
     let response = request!(Route::UsersMeConnections,
                             get,
@@ -1121,6 +1175,7 @@ pub fn get_user_connections() -> Result<Vec<UserConnection>> {
                       UserConnection::decode)
 }
 
+/// Gets our DM channels.
 pub fn get_user_dm_channels() -> Result<Vec<PrivateChannel>> {
     let response = request!(Route::UsersMeChannels, get, "/users/@me/channels");
 
@@ -1128,6 +1183,7 @@ pub fn get_user_dm_channels() -> Result<Vec<PrivateChannel>> {
                       PrivateChannel::decode)
 }
 
+/// Gets all voice regions.
 pub fn get_voice_regions() -> Result<Vec<VoiceRegion>> {
     let response = request!(Route::VoiceRegions, get, "/voice/regions");
 
@@ -1183,6 +1239,7 @@ pub fn get_webhook_with_token(webhook_id: u64, token: &str) -> Result<Webhook> {
     Webhook::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Kicks a member from a guild.
 pub fn kick_member(guild_id: u64, user_id: u64) -> Result<()> {
     verify(204, request!(Route::GuildsIdMembersId(guild_id),
                          delete,
@@ -1191,6 +1248,7 @@ pub fn kick_member(guild_id: u64, user_id: u64) -> Result<()> {
                          user_id))
 }
 
+/// Leaves a group DM.
 pub fn leave_group(guild_id: u64) -> Result<Group> {
     let response = request!(Route::None,
                             delete,
@@ -1200,6 +1258,7 @@ pub fn leave_group(guild_id: u64) -> Result<Group> {
     Group::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Leaves a guild.
 pub fn leave_guild(guild_id: u64) -> Result<PartialGuild> {
     let response = request!(Route::UsersMeGuildsId,
                             delete,
@@ -1209,12 +1268,14 @@ pub fn leave_guild(guild_id: u64) -> Result<PartialGuild> {
     PartialGuild::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Logs out. That's supposed to disable the token but doesn't.
 pub fn logout(map: Value) -> Result<()> {
     let body = try!(serde_json::to_string(&map));
 
     verify(204, request!(Route::None, post(body), "/auth/logout"))
 }
 
+/// Deletes a user from group DM.
 pub fn remove_group_recipient(group_id: u64, user_id: u64)
     -> Result<()> {
     verify(204, request!(Route::None,
@@ -1224,6 +1285,7 @@ pub fn remove_group_recipient(group_id: u64, user_id: u64)
                          user_id))
 }
 
+/// Sends a file to a channel.
 pub fn send_file<R: Read>(channel_id: u64,
                           mut file: R,
                           filename: &str,
@@ -1259,6 +1321,7 @@ pub fn send_file<R: Read>(channel_id: u64,
     Message::decode(try!(serde_json::from_reader(try!(request.send()))))
 }
 
+/// Sends a message to a channel.
 pub fn send_message(channel_id: u64, map: Value) -> Result<Message> {
     let body = try!(serde_json::to_string(&map));
     let response = request!(Route::ChannelsIdMessages(channel_id),
@@ -1269,6 +1332,7 @@ pub fn send_message(channel_id: u64, map: Value) -> Result<Message> {
     Message::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Pins a message in a channel.
 pub fn pin_message(channel_id: u64, message_id: u64) -> Result<()> {
     verify(204, request!(Route::ChannelsIdPinsMessageId(channel_id),
                          put,
@@ -1277,6 +1341,7 @@ pub fn pin_message(channel_id: u64, message_id: u64) -> Result<()> {
                          message_id))
 }
 
+/// Unbans a user from a guild.
 pub fn remove_ban(guild_id: u64, user_id: u64) -> Result<()> {
     verify(204, request!(Route::GuildsIdBansUserId(guild_id),
                          delete,
@@ -1285,7 +1350,7 @@ pub fn remove_ban(guild_id: u64, user_id: u64) -> Result<()> {
                          user_id))
 }
 
-/// Removes a single [`Role`] from a [`Member`] in a [`Guild`].
+/// Deletes a single [`Role`] from a [`Member`] in a [`Guild`].
 ///
 /// **Note**: Requires the [Manage Roles] permission and respect of role
 /// hierarchy.
@@ -1303,6 +1368,7 @@ pub fn remove_member_role(guild_id: u64, user_id: u64, role_id: u64) -> Result<(
                          role_id))
 }
 
+/// Starts removing some members from a guild based on the last time they've been online.
 pub fn start_guild_prune(guild_id: u64, map: Value)
     -> Result<GuildPrune> {
     let body = try!(serde_json::to_string(&map));
@@ -1314,6 +1380,7 @@ pub fn start_guild_prune(guild_id: u64, map: Value)
     GuildPrune::decode(try!(serde_json::from_reader(response)))
 }
 
+/// Adds an integration to a guild.
 pub fn start_integration_sync(guild_id: u64, integration_id: u64)
     -> Result<()> {
     verify(204, request!(Route::GuildsIdIntegrationsIdSync(guild_id),
@@ -1323,6 +1390,7 @@ pub fn start_integration_sync(guild_id: u64, integration_id: u64)
                          integration_id))
 }
 
+/// Unpins a message from a channel.
 pub fn unpin_message(channel_id: u64, message_id: u64) -> Result<()> {
     verify(204, request!(Route::ChannelsIdPinsMessageId(channel_id),
                          delete,
diff --git a/src/model/event.rs b/src/model/event.rs
index 673a3e5..694ebf1 100644
--- a/src/model/event.rs
+++ b/src/model/event.rs
@@ -1,3 +1,5 @@
+//! All the events this library handles.
+
 use std::collections::{BTreeMap, HashMap};
 use super::utils::*;
 use super::*;
diff --git a/src/model/misc.rs b/src/model/misc.rs
index 3a17d96..ebf1979 100644
--- a/src/model/misc.rs
+++ b/src/model/misc.rs
@@ -12,6 +12,7 @@ use super::{
 };
 use ::internal::prelude::*;
 
+/// Allows something - such as a channel or role - to be mentioned in a message.
 pub trait Mentionable {
     fn mention(&self) -> String;
 }