Add some model docs, deprecate Role::edit_role

Deprecate `Role::edit_role` and rename it to `Role::edit`.

12 files changed, 174 insertions, 35 deletions

diff --git a/src/builder/create_embed.rs b/src/builder/create_embed.rs
index ff4e2c4..0099936 100644
--- a/src/builder/create_embed.rs
+++ b/src/builder/create_embed.rs
@@ -2,7 +2,7 @@
 //!
 //! This is a set of embed builders for rich embeds.
 //!
-//! These are used in the [`Context::send_message`] and
+//! These are used in the [`ChannelId::send_message`] and
 //! [`ExecuteWebhook::embeds`] methods, both as part of builders.
 //!
 //! The only builder that should be exposed is [`CreateEmbed`]. The rest of
@@ -10,7 +10,7 @@
 //!
 //! Documentation for embeds can be found [here].
 //!
-//! [`Context::send_message`]: ../client/struct.Context.html#method.send_message
+//! [`ChannelId::send_message`]: ../model/struct.ChannelId.html#method.send_message
 //! [`CreateEmbed`]: struct.CreateEmbed.html
 //! [`ExecuteWebhook::embeds`]: struct.ExecuteWebhook.html#method.embeds
 //! [here]: https://discordapp.com/developers/docs/resources/channel#embed-object
@@ -25,14 +25,14 @@ use ::model::Embed;
 use ::utils::Colour;
 
 /// A builder to create a fake [`Embed`] object, for use with the
-/// [`Context::send_message`] and [`ExecuteWebhook::embeds`] methods.
+/// [`ChannelId::send_message`] and [`ExecuteWebhook::embeds`] methods.
 ///
 /// # Examples
 ///
-/// Refer to the documentation for [`Context::send_message`] for a very in-depth
+/// Refer to the documentation for [`ChannelId::send_message`] for a very in-depth
 /// example on how to use this.
 ///
-/// [`Context::send_message`]: ../client/struct.Context.html#method.send_message
+/// [`ChannelId::send_message`]: ../model/struct.ChannelId.html#method.send_message
 /// [`Embed`]: ../model/struct.Embed.html
 /// [`ExecuteWebhook::embeds`]: struct.ExecuteWebhook.html#method.embeds
 #[derive(Clone, Debug)]
diff --git a/src/builder/create_invite.rs b/src/builder/create_invite.rs
index 98fc2b9..bd76ed8 100644
--- a/src/builder/create_invite.rs
+++ b/src/builder/create_invite.rs
@@ -2,7 +2,7 @@ use serde_json::Value;
 use std::default::Default;
 use ::internal::prelude::*;
 
-/// A builder to create a [`RichInvite`] for use via [`Context::create_invite`].
+/// A builder to create a [`RichInvite`] for use via [`GuildChannel::create_invite`].
 ///
 /// This is a structured and cleaner way of creating an invite, as all
 /// parameters are optional.
@@ -52,7 +52,7 @@ use ::internal::prelude::*;
 /// });
 /// ```
 ///
-/// [`Context::create_invite`]: ../client/struct.Context.html#method.create_invite
+/// [`GuildChannel::create_invite`]: ../model/struct.GuildChannel.html#method.create_invite
 /// [`RichInvite`]: ../model/struct.Invite.html
 #[derive(Clone, Debug)]
 pub struct CreateInvite(pub JsonMap);
diff --git a/src/builder/create_message.rs b/src/builder/create_message.rs
index 14be4ca..e9e8bf5 100644
--- a/src/builder/create_message.rs
+++ b/src/builder/create_message.rs
@@ -3,7 +3,7 @@ use ::model::ReactionType;
 use ::internal::prelude::*;
 
 /// A builder to specify the contents of an [`http::send_message`] request,
-/// primarily meant for use through [`Context::send_message`].
+/// primarily meant for use through [`ChannelId::send_message`].
 ///
 /// There are two situations where different field requirements are present:
 ///
@@ -12,7 +12,7 @@ use ::internal::prelude::*;
 /// set.
 ///
 /// Note that if you only need to send the content of a message, without
-/// specifying other fields, then [`Context::say`] may be a more preferable
+/// specifying other fields, then [`ChannelId::say`] may be a more preferable
 /// option.
 ///
 /// # Examples
@@ -32,8 +32,8 @@ use ::internal::prelude::*;
 ///         .description("With a description")));
 /// ```
 ///
-/// [`Context::say`]: ../client/struct.Context.html#method.say
-/// [`Context::send_message`]: ../client/struct.Context.html#method.send_message
+/// [`ChannelId::say`]: ../model/struct.ChannelId.html#method.say
+/// [`ChannelId::send_message`]: ../model/struct.ChannelId.html#method.send_message
 /// [`content`]: #method.content
 /// [`embed`]: #method.embed
 /// [`http::send_message`]: ../http/fn.send_message.html
diff --git a/src/builder/edit_channel.rs b/src/builder/edit_channel.rs
index 2bf8979..9d859c7 100644
--- a/src/builder/edit_channel.rs
+++ b/src/builder/edit_channel.rs
@@ -1,11 +1,6 @@
 use ::internal::prelude::*;
 
-/// A builder to edit a [`GuildChannel`] for use via one of a couple methods.
-///
-/// These methods are:
-///
-/// - [`Context::edit_channel`]
-/// - [`GuildChannel::edit`]
+/// A builder to edit a [`GuildChannel`] for use via [`GuildChannel::edit`]
 ///
 /// Defaults are not directly provided by the builder itself.
 ///
@@ -20,7 +15,6 @@ use ::internal::prelude::*;
 /// }
 /// ```
 ///
-/// [`Context::edit_channel`]: ../client/struct.Context.html#method.edit_channel
 /// [`GuildChannel`]: ../model/struct.GuildChannel.html
 /// [`GuildChannel::edit`]: ../model/struct.GuildChannel.html#method.edit
 #[derive(Clone, Debug, Default)]
diff --git a/src/builder/edit_guild.rs b/src/builder/edit_guild.rs
index c01b8ea..e74e54e 100644
--- a/src/builder/edit_guild.rs
+++ b/src/builder/edit_guild.rs
@@ -2,14 +2,13 @@ use ::internal::prelude::*;
 use ::model::{ChannelId, Region, UserId, VerificationLevel};
 
 /// A builder to optionally edit certain fields of a [`Guild`]. This is meant
-/// for usage with [`Context::edit_guild`] and [`LiveGuild::edit`].
+/// for usage with [`Guild::edit`].
 ///
 /// **Note**: Editing a guild requires that the current user have the
 /// [Manage Guild] permission.
 ///
-/// [`Context::edit_guild`]: ../client/struct.Context.html
+/// [`Guild::edit`]: ../model/struct.Guild.html#method.edit
 /// [`Guild`]: ../model/struct.Guild.html
-/// [`LiveGuild::edit`]: ../model/struct.LiveGuild.html#method.edit
 /// [Manage Guild]: ../model/permissions/constant.MANAGE_GUILD.html
 #[derive(Clone, Debug, Default)]
 pub struct EditGuild(pub Map<String, Value>);
diff --git a/src/builder/edit_member.rs b/src/builder/edit_member.rs
index 044d8f2..3fce146 100644
--- a/src/builder/edit_member.rs
+++ b/src/builder/edit_member.rs
@@ -2,9 +2,8 @@ use ::model::{ChannelId, RoleId};
 use ::internal::prelude::*;
 
 /// A builder which edits the properties of a [`Member`], to be used in
-/// conjunction with [`Context::edit_member`] and [`Member::edit`].
+/// conjunction with [`Member::edit`].
 ///
-/// [`Context::edit_member`]: ../client/struct.Context.html#method.edit_member
 /// [`Member`]: ../model/struct.Member.html
 /// [`Member::edit`]: ../model/struct.Member.html#method.edit
 #[derive(Clone, Debug, Default)]
diff --git a/src/builder/edit_profile.rs b/src/builder/edit_profile.rs
index a4b5c99..2d4df85 100644
--- a/src/builder/edit_profile.rs
+++ b/src/builder/edit_profile.rs
@@ -1,9 +1,9 @@
 use ::internal::prelude::*;
 
 /// A builder to edit the current user's settings, to be used in conjunction
-/// with [`Context::edit_profile`].
+/// with [`CurrentUser::edit`].
 ///
-/// [`Context::edit_profile`]: ../client/struct.Context.html#method.edit_profile
+/// [`CurrentUser::edit`]: ../model/struct.CurrentUser.html#method.edit
 #[derive(Clone, Debug, Default)]
 pub struct EditProfile(pub JsonMap);
 
diff --git a/src/builder/edit_role.rs b/src/builder/edit_role.rs
index f17947a..6be09fe 100644
--- a/src/builder/edit_role.rs
+++ b/src/builder/edit_role.rs
@@ -2,14 +2,15 @@ use std::default::Default;
 use ::internal::prelude::*;
 use ::model::{Permissions, Role, permissions};
 
-/// A builer to create or edit a [`Role`] for use via a number of model and
-/// context methods.
+/// A builer to create or edit a [`Role`] for use via a number of model methods.
 ///
 /// These are:
 ///
-/// - [`Context::create_role`]
-/// - [`Context::edit_role`]
+/// - [`PartialGuild::create_role`]
 /// - [`Guild::create_role`]
+/// - [`Guild::edit_role`]
+/// - [`GuildId::create_role`]
+/// - [`GuildId::edit_role`]
 /// - [`Role::edit`]
 ///
 /// Defaults are provided for each parameter on role creation.
@@ -30,9 +31,11 @@ use ::model::{Permissions, Role, permissions};
 ///     .name("a test role"));
 /// ```
 ///
-/// [`Context::create_role`]: ../client/struct.Context.html#method.create_role
-/// [`Context::edit_role`]: ../client/struct.Context.html#method.edit_role
+/// [`PartialGuild::create_role`]: ../model/struct.PartialGuild.html#method.create_role
 /// [`Guild::create_role`]: ../model/struct.Guild.html#method.create_role
+/// [`Guild::edit_role`]: ../model/struct.Guild.html#method.edit_role
+/// [`GuildId::create_role`]: ../model/struct.GuildId.html#method.create_role
+/// [`GuildId::edit_role`]: ../model/struct.GuildId.html#method.edit_role
 /// [`Role`]: ../model/struct.Role.html
 /// [`Role::edit`]: ../model/struct.Role.html#method.edit
 #[derive(Clone, Debug)]
diff --git a/src/model/channel/embed.rs b/src/model/channel/embed.rs
index 0db22ef..f46f0d3 100644
--- a/src/model/channel/embed.rs
+++ b/src/model/channel/embed.rs
@@ -68,6 +68,22 @@ impl Embed {
     /// This should only be useful in conjunction with [`Webhook::execute`].
     ///
     /// [`Webhook::execute`]: struct.Webhook.html
+    ///
+    /// # Examples
+    ///
+    /// Create an embed:
+    ///
+    /// ```rust,no_run
+    /// use serenity::model::Embed;
+    ///
+    /// let embed = Embed::fake(|e| e
+    ///     .title("Embed title")
+    ///     .description("Making a basic embed")
+    ///     .field(|f| f
+    ///         .name("A field")
+    ///         .value("Has some content.")
+    ///         .inline(false)));
+    /// ```
     #[inline]
     pub fn fake<F>(f: F) -> Value where F: FnOnce(CreateEmbed) -> CreateEmbed {
         Value::Object(f(CreateEmbed::default()).0)
diff --git a/src/model/gateway.rs b/src/model/gateway.rs
index 52ec9b0..8458bbb 100644
--- a/src/model/gateway.rs
+++ b/src/model/gateway.rs
@@ -39,6 +39,23 @@ impl Game {
     /// Creates a `Game` struct that appears as a `Playing <name>` status.
     ///
     /// **Note**: Maximum `name` length is 128.
+    ///
+    /// # Examples
+    ///
+    /// Create a command that sets the current game being played:
+    ///
+    /// ```rust,no_run
+    /// # #[macro_use] extern crate serenity;
+    /// #
+    /// use serenity::model::Game;
+    ///
+    /// command!(game(ctx, _msg, args) {
+    ///     let name = args.join(" ");
+    ///     ctx.set_game(Game::playing(&name)); 
+    /// });
+    /// #
+    /// # fn main() {}
+    /// ```
     pub fn playing(name: &str) -> Game {
         Game {
             kind: GameType::Playing,
@@ -50,6 +67,24 @@ impl Game {
     /// Creates a `Game` struct that appears as a `Streaming <name>` status.
     ///
     /// **Note**: Maximum `name` length is 128.
+    ///
+    /// # Examples
+    ///
+    /// Create a command that sets the current game and stream:
+    ///
+    /// ```rust,no_run
+    /// # #[macro_use] extern crate serenity;
+    /// #
+    /// use serenity::model::Game;
+    ///
+    /// // Assumes command has min_args set to 2.
+    /// command!(stream(ctx, _msg, args, stream: String) {
+    ///     let name = args[1..].join(" ");
+    ///     ctx.set_game(Game::streaming(&name, &stream)); 
+    /// });
+    /// #
+    /// # fn main() {}
+    /// ```
     pub fn streaming(name: &str, url: &str) -> Game {
         Game {
             kind: GameType::Streaming,
diff --git a/src/model/guild/emoji.rs b/src/model/guild/emoji.rs
index f2c7e91..9a8ad39 100644
--- a/src/model/guild/emoji.rs
+++ b/src/model/guild/emoji.rs
@@ -47,6 +47,28 @@ impl Emoji {
     /// **Note**: Only user accounts may use this method.
     ///
     /// [Manage Emojis]: permissions/constant.MANAGE_EMOJIS.html
+    ///
+    /// # Examples
+    ///
+    /// Delete a given emoji:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::model::{Emoji, EmojiId};
+    /// #
+    /// # let mut emoji = Emoji {
+    /// #     id: EmojiId(7),
+    /// #     name: String::from("blobface"),
+    /// #     managed: false,
+    /// #     require_colons: false,
+    /// #     roles: vec![],
+    /// # };
+    /// #
+    /// // assuming emoji has been set already
+    /// match emoji.delete() {
+    ///     Ok(()) => println!("Emoji deleted."),
+    ///     Err(_) => println!("Could not delete emoji.")
+    /// }
+    /// ```
     #[cfg(feature="cache")]
     pub fn delete(&self) -> Result<()> {
         match self.find_guild_id() {
@@ -62,6 +84,26 @@ impl Emoji {
     /// **Note**: Only user accounts may use this method.
     ///
     /// [Manage Emojis]: permissions/constant.MANAGE_EMOJIS.html
+    ///
+    /// # Examples
+    ///
+    /// Change the name of an emoji:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::model::{Emoji, EmojiId};
+    /// #
+    /// # let mut emoji = Emoji {
+    /// #     id: EmojiId(7),
+    /// #     name: String::from("blobface"),
+    /// #     managed: false,
+    /// #     require_colons: false,
+    /// #     roles: vec![],
+    /// # };
+    /// #
+    /// // assuming emoji has been set already
+    /// let _ = emoji.edit("blobuwu");
+    /// assert_eq!(emoji.name, "blobuwu");
+    /// ```
     #[cfg(feature="cache")]
     pub fn edit(&mut self, name: &str) -> Result<()> {
         match self.find_guild_id() {
@@ -86,6 +128,27 @@ impl Emoji {
     /// Finds the [`Guild`] that owns the emoji by looking through the Cache.
     ///
     /// [`Guild`]: struct.Guild.html
+    ///
+    /// # Examples
+    ///
+    /// Print the guild id that owns this emoji:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::model::{Emoji, EmojiId};
+    /// #
+    /// # let mut emoji = Emoji {
+    /// #     id: EmojiId(7),
+    /// #     name: String::from("blobface"),
+    /// #     managed: false,
+    /// #     require_colons: false,
+    /// #     roles: vec![],
+    /// # };
+    /// #
+    /// // assuming emoji has been set already
+    /// if let Some(guild_id) = emoji.find_guild_id() {
+    ///     println!("{} is owned by {}", emoji.name, guild_id);
+    /// }
+    /// ```
     #[cfg(feature="cache")]
     pub fn find_guild_id(&self) -> Option<GuildId> {
         for guild in CACHE.read().unwrap().guilds.values() {
@@ -100,6 +163,25 @@ impl Emoji {
     }
 
     /// Generates a URL to the emoji's image.
+    ///
+    /// # Examples
+    ///
+    /// Print the direct link to the given emoji:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::model::{Emoji, EmojiId};
+    /// #
+    /// # let mut emoji = Emoji {
+    /// #     id: EmojiId(7),
+    /// #     name: String::from("blobface"),
+    /// #     managed: false,
+    /// #     require_colons: false,
+    /// #     roles: vec![],
+    /// # };
+    /// #
+    /// // assuming emoji has been set already
+    /// println!("Direct link to emoji image: {}", emoji.url());
+    /// ```
     #[inline]
     pub fn url(&self) -> String {
         format!(cdn!("/emojis/{}.png"), self.id)
diff --git a/src/model/guild/role.rs b/src/model/guild/role.rs
index df65e61..8383675 100644
--- a/src/model/guild/role.rs
+++ b/src/model/guild/role.rs
@@ -83,22 +83,33 @@ impl Role {
     ///
     /// Make a role hoisted:
     ///
-    /// ```rust,ignore
-    /// // assuming a `guild` and `role_id` have been bound
+    /// ```rust,no_run
+    /// # use serenity::model::RoleId;
+    /// # let role = RoleId(7).find().unwrap();
+    /// // assuming a `role` has already been bound
     //
-    /// guild.edit_role(role_id, |r| r.hoist(true));
+    /// role.edit(|r| r.hoist(true));
     /// ```
     ///
     /// [`Role`]: struct.Role.html
     /// [Manage Roles]: permissions/constant.MANAGE_ROLES.html
     #[cfg(all(feature="builder", feature="cache"))]
-    pub fn edit_role<F: FnOnce(EditRole) -> EditRole>(&self, f: F) -> Result<Role> {
+    pub fn edit<F: FnOnce(EditRole) -> EditRole>(&self, f: F) -> Result<Role> {
         match self.find_guild() {
             Ok(guild_id) => guild_id.edit_role(self.id, f),
             Err(why) => Err(why),
         }
     }
 
+    /// Alias of [`edit`]
+    ///
+    /// [`edit`]: struct.Role.html#method.edit
+    #[deprecated(since="0.2.1", note="Please use `edit` instead.")]
+    #[cfg(all(feature="builder", feature="cache"))]
+    pub fn edit_role<F: FnOnce(EditRole) -> EditRole>(&self, f: F) -> Result<Role> {
+        self.edit(f)
+    }
+
     /// Searches the cache for the guild that owns the role.
     ///
     /// # Errors