Improve docs and add new message builder methods

Add documentation for some missing methods - such as Game methods - and
add more methods to the Message Builder.

4 files changed, 46 insertions, 6 deletions

diff --git a/src/model/channel.rs b/src/model/channel.rs
index 9a3f9ea..a95b1f3 100644
--- a/src/model/channel.rs
+++ b/src/model/channel.rs
@@ -139,7 +139,7 @@ impl Attachment {
     ///
     /// // Make sure that the directory to store images in exists.
     /// fs::create_dir_all("./attachment_downloads")
-    ///     .expect("err making directory");
+    ///     .expect("Error making directory");
     ///
     /// let token = env::var("DISCORD_TOKEN").expect("token in environment");
     /// let mut client = Client::login_bot(&token);
@@ -820,6 +820,16 @@ impl GuildChannel {
         rest::broadcast_typing(self.id.0)
     }
 
+    /// Creates an invite leading to the given channel.
+    ///
+    /// # Examples
+    ///
+    /// Create an invite that can only be used 5 times:
+    ///
+    /// ```rust,ignore
+    /// let invite = channel.create_invite(|i| i
+    ///     .max_uses(5));
+    /// ```
     #[cfg(feature = "methods")]
     pub fn create_invite<F>(&self, f: F) -> Result<RichInvite>
         where F: FnOnce(CreateInvite) -> CreateInvite {
@@ -875,6 +885,19 @@ impl GuildChannel {
         rest::delete_channel(self.id.0)
     }
 
+    /// Modifies a channel's settings, such as its position or name.
+    ///
+    /// Refer to `EditChannel`s documentation for a full list of methods.
+    ///
+    /// # Examples
+    ///
+    /// Change a voice channels name and bitrate:
+    ///
+    /// ```rust,ignore
+    /// channel.edit(|c| c
+    ///     .name("test")
+    ///     .bitrate(71));
+    /// ```
     #[cfg(feature = "methods")]
     pub fn edit<F>(&mut self, f: F) -> Result<()>
         where F: FnOnce(EditChannel) -> EditChannel {
@@ -919,6 +942,7 @@ impl GuildChannel {
         self.id.mention()
     }
 
+    /// Gets all channel's pins.
     #[cfg(feature = "methods")]
     pub fn pins(&self) -> Result<Vec<Message>> {
         rest::get_pins(self.id.0)
diff --git a/src/model/gateway.rs b/src/model/gateway.rs
index 101f050..30ed695 100644
--- a/src/model/gateway.rs
+++ b/src/model/gateway.rs
@@ -3,6 +3,7 @@ use super::*;
 use ::internal::prelude::*;
 
 impl Game {
+    /// Creates a `Game` struct that appears as a `**Playing** <name>` status.
     #[cfg(feature="methods")]
     pub fn playing(name: &str) -> Game {
         Game {
@@ -12,6 +13,7 @@ impl Game {
         }
     }
 
+    /// Creates a `Game` struct that appears as a `**Streaming** <name>` status.
     #[cfg(feature="methods")]
     pub fn streaming(name: &str, url: &str) -> Game {
         Game {
diff --git a/src/model/id.rs b/src/model/id.rs
index cba72ae..5f534ec 100644
--- a/src/model/id.rs
+++ b/src/model/id.rs
@@ -50,6 +50,7 @@ impl ChannelId {
 }
 
 impl From<Channel> for ChannelId {
+    /// Gets the Id of a `Channel`.
     fn from(channel: Channel) -> ChannelId {
         match channel {
             Channel::Group(group) => group.channel_id,
@@ -60,18 +61,21 @@ impl From<Channel> for ChannelId {
 }
 
 impl From<PrivateChannel> for ChannelId {
+    /// Gets the Id of a private channel.
     fn from(private_channel: PrivateChannel) -> ChannelId {
         private_channel.id
     }
 }
 
 impl From<GuildChannel> for ChannelId {
+    /// Gets the Id of a guild channel.
     fn from(public_channel: GuildChannel) -> ChannelId {
         public_channel.id
     }
 }
 
 impl From<Emoji> for EmojiId {
+    /// Gets the Id of an `Emoji`.
     fn from(emoji: Emoji) -> EmojiId {
         emoji.id
     }
@@ -122,42 +126,49 @@ impl GuildId {
 }
 
 impl From<PartialGuild> for GuildId {
+    /// Gets the Id of a partial guild.
     fn from(guild: PartialGuild) -> GuildId {
         guild.id
     }
 }
 
 impl From<GuildInfo> for GuildId {
+    /// Gets the Id of Guild information struct.
     fn from(guild_info: GuildInfo) -> GuildId {
         guild_info.id
     }
 }
 
 impl From<InviteGuild> for GuildId {
+    /// Gets the Id of Invite Guild struct.
     fn from(invite_guild: InviteGuild) -> GuildId {
         invite_guild.id
     }
 }
 
 impl From<Guild> for GuildId {
+    /// Gets the Id of Guild.
     fn from(live_guild: Guild) -> GuildId {
         live_guild.id
     }
 }
 
 impl From<Integration> for IntegrationId {
+    /// Gets the Id of integration.
     fn from(integration: Integration) -> IntegrationId {
         integration.id
     }
 }
 
 impl From<Message> for MessageId {
+    /// Gets the Id of a `Message`.
     fn from(message: Message) -> MessageId {
         message.id
     }
 }
 
 impl From<Role> for RoleId {
+    /// Gets the Id of a `Role`.
     fn from(role: Role) -> RoleId {
         role.id
     }
@@ -192,18 +203,21 @@ impl RoleId {
 }
 
 impl From<CurrentUser> for UserId {
+    /// Gets the Id of a `CurrentUser` struct.
     fn from(current_user: CurrentUser) -> UserId {
         current_user.id
     }
 }
 
 impl From<Member> for UserId {
+    /// Gets the Id of a `Member`.
     fn from(member: Member) -> UserId {
         member.user.id
     }
 }
 
 impl From<User> for UserId {
+    /// Gets the Id of a `User`.
     fn from(user: User) -> UserId {
         user.id
     }
diff --git a/src/model/webhook.rs b/src/model/webhook.rs
index 4553f30..9d3a393 100644
--- a/src/model/webhook.rs
+++ b/src/model/webhook.rs
@@ -41,7 +41,7 @@ impl Webhook {
     /// let mut webhook = rest::get_webhook_with_token(id, token)
     ///     .expect("valid webhook");
     ///
-    /// let _ = webhook.edit(Some("new name"), None).expect("err editing");
+    /// let _ = webhook.edit(Some("new name"), None).expect("Error editing");
     /// ```
     ///
     /// Setting a webhook's avatar:
@@ -56,9 +56,9 @@ impl Webhook {
     ///     .expect("valid webhook");
     ///
     /// let image = serenity::utils::read_image("./webhook_img.png")
-    ///     .expect("err reading image");
+    ///     .expect("Error reading image");
     ///
-    /// let _ = webhook.edit(None, Some(&image)).expect("err editing");
+    /// let _ = webhook.edit(None, Some(&image)).expect("Error editing");
     /// ```
     ///
     /// [`rest::edit_webhook`]: ../client/rest/fn.edit_webhook.html
@@ -114,7 +114,7 @@ impl Webhook {
     /// let mut webhook = rest::get_webhook_with_token(id, token)
     ///     .expect("valid webhook");
     ///
-    /// let _ = webhook.execute(|w| w.content("test")).expect("err executing");
+    /// let _ = webhook.execute(|w| w.content("test")).expect("Error executing");
     /// ```
     ///
     /// Execute a webhook with message content of `test`, overriding the
@@ -141,7 +141,7 @@ impl Webhook {
     ///     .content("test")
     ///     .username("serenity")
     ///     .embeds(vec![embed]))
-    ///     .expect("err executing");
+    ///     .expect("Error executing");
     /// ```
     #[cfg(feature="methods")]
     pub fn execute<F>(&self, f: F) -> Result<Message>