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.

6 files changed, 274 insertions, 28 deletions

diff --git a/src/builder/create_invite.rs b/src/builder/create_invite.rs
index 67e33fc..98fc2b9 100644
--- a/src/builder/create_invite.rs
+++ b/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);
diff --git a/src/builder/edit_guild.rs b/src/builder/edit_guild.rs
index aa08341..c01b8ea 100644
--- a/src/builder/edit_guild.rs
+++ b/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
diff --git a/src/builder/edit_profile.rs b/src/builder/edit_profile.rs
index d63a512..a4b5c99 100644
--- a/src/builder/edit_profile.rs
+++ b/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
diff --git a/src/builder/edit_role.rs b/src/builder/edit_role.rs
index 64cc42b..f17947a 100644
--- a/src/builder/edit_role.rs
+++ b/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"));
diff --git a/src/builder/execute_webhook.rs b/src/builder/execute_webhook.rs
index 67e10be..68a39fc 100644
--- a/src/builder/execute_webhook.rs
+++ b/src/builder/execute_webhook.rs
@@ -15,7 +15,7 @@ use ::internal::prelude::*;
 /// Creating two embeds, and then sending them as part of the delivery
 /// payload of [`Webhook::execute`]:
 ///
-/// ```rust,ignore
+/// ```rust,no_run
 /// use serenity::http;
 /// use serenity::model::Embed;
 /// use serenity::utils::Colour;
@@ -57,6 +57,22 @@ pub struct ExecuteWebhook(pub JsonMap);
 
 impl ExecuteWebhook {
     /// Override the default avatar of the webhook with an image URL.
+    ///
+    /// # Examples
+    ///
+    /// Overriding the default avatar:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::http;
+    /// #
+    /// # let webhook = http::get_webhook_with_token(0, "").unwrap();
+    /// #
+    /// let avatar_url = "https://i.imgur.com/KTs6whd.jpg";
+    ///
+    /// let _ = webhook.execute(|w| w
+    ///     .avatar_url(avatar_url)
+    ///     .content("Here's a webhook"));
+    /// ```
     pub fn avatar_url(mut self, avatar_url: &str) -> Self {
         self.0.insert("avatar_url".to_owned(), Value::String(avatar_url.to_owned()));
 
@@ -68,6 +84,20 @@ impl ExecuteWebhook {
     /// Note that when setting at least one embed via [`embeds`], this may be
     /// omitted.
     ///
+    /// # Examples
+    ///
+    /// Sending a webhook with a content of `"foo"`:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::client::rest;
+    /// #
+    /// # let webhook = rest::get_webhook_with_token(0, "").unwrap();
+    /// #
+    /// if let Err(why) = webhook.execute(|w| w.content("foo")) {
+    ///     println!("Err sending webhook: {:?}", why);
+    /// }
+    /// ```
+    ///
     /// [`embeds`]: #method.embeds
     pub fn content(mut self, content: &str) -> Self {
         self.0.insert("content".to_owned(), Value::String(content.to_owned()));
@@ -96,7 +126,19 @@ impl ExecuteWebhook {
 
     /// Whether the message is a text-to-speech message.
     ///
-    /// Think carefully before setting this to `true`.
+    /// # Examples
+    ///
+    /// Sending a webhook with text-to-speech enabled:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::client::rest;
+    /// #
+    /// # let webhook = rest::get_webhook_with_token(0, "").unwrap();
+    /// #
+    /// if let Err(why) = webhook.execute(|w| w.content("hello").tts(true)) {
+    ///     println!("Err sending webhook: {:?}", why);
+    /// }
+    /// ```
     pub fn tts(mut self, tts: bool) -> Self {
         self.0.insert("tts".to_owned(), Value::Bool(tts));
 
@@ -104,6 +146,20 @@ impl ExecuteWebhook {
     }
 
     /// Override the default username of the webhook.
+    ///
+    /// # Examples
+    ///
+    /// Overriuding the username to `"hakase"`:
+    ///
+    /// ```rust,no_run
+    /// # use serenity::client::rest;
+    /// #
+    /// # let webhook = rest::get_webhook_with_token(0, "").unwrap();
+    /// #
+    /// if let Err(why) = webhook.execute(|w| w.content("hello").username("hakase")) {
+    ///     println!("Err sending webhook: {:?}", why);
+    /// }
+    /// ```
     pub fn username(mut self, username: &str) -> Self {
         self.0.insert("username".to_owned(), Value::String(username.to_owned()));
 
@@ -114,9 +170,17 @@ impl ExecuteWebhook {
 impl Default for ExecuteWebhook {
     /// Returns a default set of values for a [`Webhook`] execution.
     ///
-    /// The only default value is [`tts`] being set to `true`. In the event that
-    /// there is a bug that Discord defaults `tts` to `true`, at least
-    /// serenity won't be a part of it.
+    /// The only default value is [`tts`] being set to `false`.
+    ///
+    /// # Examples
+    ///
+    /// Creating an `ExecuteWebhook` builder:
+    ///
+    /// ```rust
+    /// use serenity::utils::builder::ExecuteWebhook;
+    ///
+    /// let executer = ExecuteWebhook::default();
+    /// ```
     ///
     /// [`Webhook`]: ../model/struct.Webhook.html
     /// [`tts`]: #method.tts
diff --git a/src/builder/get_messages.rs b/src/builder/get_messages.rs
index b9142a1..193adca 100644
--- a/src/builder/get_messages.rs
+++ b/src/builder/get_messages.rs
@@ -18,9 +18,37 @@ use ::model::MessageId;
 /// does not _need_ to be called and defaults to a value of 50.
 ///
 /// This should be used only for retrieving messages; see
-/// [`Client::get_messages`] for examples.
+/// [`GuildChannel::messages`] for examples.
 ///
-/// [`Client::get_messages`]: ../client/struct.Client.html#method.get_messages
+/// # Examples
+///
+/// Creating a `GetMessages` builder to retrieve the first 25 messages after the
+/// message with an Id of `158339864557912064`:
+///
+/// ```rust,no_run
+/// # use std::error::Error;
+/// #
+/// # fn try_main() -> Result<(), Box<Error>> {
+/// use serenity::model::{ChannelId, MessageId};
+/// use serenity::builder::GetMessages;
+///
+/// let retriever = GetMessages::default()
+///     .after(MessageId(158339864557912064))
+///     .limit(25);
+///
+/// // you can then pass it into a function which retrieves messages:
+/// let channel_id = ChannelId(81384788765712384);
+///
+/// let _messages = channel_id.messages(|_| retriever)?;
+/// #     Ok(())
+/// # }
+/// #
+/// # fn main() {
+/// #     try_main().unwrap();
+/// # }
+/// ```
+///
+/// [`GuildChannel::messages`]: ../model/struct.GuildChannel.html#method.messages
 #[derive(Clone, Debug, Default)]
 pub struct GetMessages(pub BTreeMap<String, u64>);