Add some model docs, deprecate Role::edit_role

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

2 files changed, 97 insertions, 4 deletions

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