Add more examples and improve some others

Add examples to some functions, and update some of the old examples to
use the `?` operator instead of unwrapping.

src/builder/create_invite.rs

@@ -11,17 +11,43 @@ use ::internal::prelude::*;
 ///
 /// Create an invite with a max age of 3600 seconds and 10 max uses:
 ///
-/// ```rust,ignore
-/// use serenity::Client;
-/// use std::env;
+/// ```rust,no_run
+/// # use serenity::Client;
+/// #
+/// # let mut client = Client::login("");
+/// #
+/// use serenity::client::CACHE;
 ///
-/// let mut client = Client::login(&env::var("DISCORD_BOT_TOKEN").unwrap());
+/// client.on_message(|_, msg| {
+///     if msg.content == "!createinvite" {
+///         let channel = match CACHE.read().unwrap().guild_channel(msg.channel_id) {
+///             Some(channel) => channel,
+///             None => {
+///                 let _ = msg.channel_id.say("Error creating invite");
 ///
-/// client.on_message(|_, message| {
-///     if message.content == "!invite" {
-///         let invite = message.channel_id.create_invite(|i| i
-///             .max_age(3600)
-///             .max_uses(10));
+///                 return;
+///             },
+///         };
+///
+///         let reader = channel.read().unwrap();
+///
+///         let invite = match reader.create_invite(|i| i.max_age(3600).max_uses(10)) {
+///             Ok(invite) => invite,
+///             Err(why) => {
+///                 println!("Err creating invite: {:?}", why);
+///
+///                 if let Err(why) = msg.channel_id.say("Error creating invite") {
+///                     println!("Err sending err msg: {:?}", why);
+///                 }
+///
+///                 return;
+///             },
+///         };
+///
+///         drop(reader);
+///
+///         let content = format!("Here's your invite: {}", invite.url());
+///         let _ = msg.channel_id.say(&content);
 ///     }
 /// });
 /// ```
@@ -37,6 +63,28 @@ impl CreateInvite {
     /// Set to `0` for an invite which does not expire after an amount of time.
     ///
     /// Defaults to `86400`, or 24 hours.
+    ///
+    /// # Examples
+    ///
+    /// Create an invite with a max age of `3600` seconds, or 1 hour:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::client::CACHE;
+    /// # use serenity::model::ChannelId;
+    /// # use std::error::Error;
+    /// #
+    /// # fn try_main() -> Result<(), Box<Error>> {
+    /// #     let channel = CACHE.read().unwrap().guild_channel(81384788765712384).unwrap();
+    /// #     let channel = channel.read().unwrap();
+    /// #
+    /// let invite = channel.create_invite(|i| i.max_age(3600))?;
+    /// #     Ok(())
+    /// # }
+    /// #
+    /// # fn main() {
+    /// #     try_main().unwrap();
+    /// # }
+    /// ```
     pub fn max_age(mut self, max_age: u64) -> Self {
         self.0.insert("max_age".to_owned(), Value::Number(Number::from(max_age)));
 
@@ -48,6 +96,28 @@ impl CreateInvite {
     /// Set to `0` for an invite which does not expire after a number of uses.
     ///
     /// Defaults to `0`.
+    ///
+    /// # Examples
+    ///
+    /// Create an invite with a max use limit of `5`:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::client::CACHE;
+    /// # use serenity::model::ChannelId;
+    /// # use std::error::Error;
+    /// #
+    /// # fn try_main() -> Result<(), Box<Error>> {
+    /// #     let channel = CACHE.read().unwrap().guild_channel(81384788765712384).unwrap();
+    /// #     let channel = channel.read().unwrap();
+    /// #
+    /// let invite = channel.create_invite(|i| i.max_uses(5))?;
+    /// #     Ok(())
+    /// # }
+    /// #
+    /// # fn main() {
+    /// #     try_main().unwrap();
+    /// # }
+    /// ```
     pub fn max_uses(mut self, max_uses: u64) -> Self {
         self.0.insert("max_uses".to_owned(), Value::Number(Number::from(max_uses)));
 
@@ -57,6 +127,28 @@ impl CreateInvite {
     /// Whether an invite grants a temporary membership.
     ///
     /// Defaults to `false`.
+    ///
+    /// # Examples
+    ///
+    /// Create an invite which is temporary:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::client::CACHE;
+    /// # use serenity::model::ChannelId;
+    /// # use std::error::Error;
+    /// #
+    /// # fn try_main() -> Result<(), Box<Error>> {
+    /// #     let channel = CACHE.read().unwrap().guild_channel(81384788765712384).unwrap();
+    /// #     let channel = channel.read().unwrap();
+    /// #
+    /// let invite = channel.create_invite(|i| i.temporary(true))?;
+    /// #     Ok(())
+    /// # }
+    /// #
+    /// # fn main() {
+    /// #     try_main().unwrap();
+    /// # }
+    /// ```
     pub fn temporary(mut self, temporary: bool) -> Self {
         self.0.insert("temporary".to_owned(), Value::Bool(temporary));
 
@@ -66,6 +158,28 @@ impl CreateInvite {
     /// Whether or not to try to reuse a similar invite.
     ///
     /// Defaults to `false`.
+    ///
+    /// # Examples
+    ///
+    /// Create an invite which is unique:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::client::CACHE;
+    /// # use serenity::model::ChannelId;
+    /// # use std::error::Error;
+    /// #
+    /// # fn try_main() -> Result<(), Box<Error>> {
+    /// #     let channel = CACHE.read().unwrap().guild_channel(81384788765712384).unwrap();
+    /// #     let channel = channel.read().unwrap();
+    /// #
+    /// let invite = channel.create_invite(|i| i.unique(true))?;
+    /// #     Ok(())
+    /// # }
+    /// #
+    /// # fn main() {
+    /// #     try_main().unwrap();
+    /// # }
+    /// ```
     pub fn unique(mut self, unique: bool) -> Self {
         self.0.insert("unique".to_owned(), Value::Bool(unique));
 
@@ -75,6 +189,16 @@ impl CreateInvite {
 
 impl Default for CreateInvite {
     /// Creates a builder with default values, setting `validate` to `null`.
+    ///
+    /// # Examples
+    ///
+    /// Create a default `CreateInvite` builder:
+    ///
+    /// ```rust
+    /// use serenity::utils::builder::CreateInvite;
+    ///
+    /// let invite_builder = CreateInvite::default();
+    /// ```
     fn default() -> CreateInvite {
         let mut map = Map::new();
         map.insert("validate".to_owned(), Value::Null);

src/builder/edit_guild.rs

@@ -49,15 +49,25 @@ impl EditGuild {
     /// Using the utility function - [`utils::read_image`] - to read an image
     /// from the cwd and encode it in base64 to send to Discord.
     ///
-    /// ```rust,ignore
+    /// ```rust,no_run
+    /// # use serenity::model::GuildId;
+    /// # use std::error::Error;
+    /// #
+    /// # fn try_main() -> Result<(), Box<Error>> {
+    /// #     let mut guild = GuildId(0).get()?;
     /// use serenity::utils;
     ///
     /// // assuming a `guild` has already been bound
     ///
-    /// let base64_icon = utils::read_image("./guild_icon.png")
-    ///     .expect("Failed to read image");
+    /// let base64_icon = utils::read_image("./guild_icon.png")?;
     ///
-    /// let _ = guild.edit(|g| g.icon(base64_icon));
+    /// guild.edit(|g| g.icon(Some(&base64_icon)))?;
+    /// #     Ok(())
+    /// # }
+    /// #
+    /// # fn main() {
+    /// #     try_main().unwrap();
+    /// # }
     /// ```
     ///
     /// [`utils::read_image`]: ../utils/fn.read_image.html
@@ -91,14 +101,23 @@ impl EditGuild {
     ///
     /// Setting the region to [`Region::UsWest`]:
     ///
-    /// ```rust,ignore
+    /// ```rust,no_run
+    /// # use serenity::model::GuildId;
+    /// # use std::error::Error;
+    /// #
+    /// # fn try_main() -> Result<(), Box<Error>> {
+    /// #     let mut guild = GuildId(0).get()?;
     /// use serenity::model::Region;
     ///
     /// // assuming a `guild` has already been bound
     ///
-    /// if let Err(why) = guild.edit(|g| g.region(Region::UsWest)) {
-    ///     println!("Error editing guild's region: {:?}", why);
-    /// }
+    /// guild.edit(|g| g.region(Region::UsWest))?;
+    /// #     Ok(())
+    /// # }
+    /// #
+    /// # fn main() {
+    /// #     try_main().unwrap();
+    /// # }
     /// ```
     ///
     /// [`Region::UsWest`]: ../model/enum.Region.html#variant.UsWest

src/builder/edit_profile.rs

@@ -18,7 +18,13 @@ impl EditProfile {
     /// A utility method - [`utils::read_image`] - is provided to read an
     /// image from a file and return its contents in base64-encoded form:
     ///
-    /// ```rust,ignore
+    /// ```rust,no_run
+    /// # use serenity::Client;
+    /// #
+    /// # let mut client = Client::login("");
+    /// #
+    /// # client.on_message(|context, _| {
+    /// #
     /// use serenity::utils;
     ///
     /// // assuming a `context` has been bound
@@ -29,6 +35,7 @@ impl EditProfile {
     /// let _ = context.edit_profile(|profile| {
     ///     profile.avatar(Some(&base64))
     /// });
+    /// # });
     /// ```
     ///
     /// [`utils::read_image`]: ../fn.read_image.html

src/builder/edit_role.rs

@@ -16,11 +16,15 @@ use ::model::{Permissions, Role, permissions};
 ///
 /// # Examples
 ///
-/// Create a hoisted, mentionable role named "a test role":
+/// Create a hoisted, mentionable role named `"a test role"`:
 ///
-/// ```rust,ignore
+/// ```rust,no_run
+/// # use serenity::model::{ChannelId, GuildId};
+/// # let (channel_id, guild_id) = (ChannelId(1), GuildId(2));
+/// #
 /// // assuming a `channel_id` and `guild_id` has been bound
-/// let role = channel_id.create_role(guild_id, |r| r
+///
+/// let role = guild_id.create_role(|r| r
 ///     .hoist(true)
 ///     .mentionable(true)
 ///     .name("a test role"));