Add some model docs, deprecate Role::edit_role

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

4 files changed, 148 insertions, 4 deletions

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