A bit of docs

7 files changed, 302 insertions, 36 deletions

diff --git a/src/utils/builder/create_embed.rs b/src/utils/builder/create_embed.rs
index 4264175..fe15ed4 100644
--- a/src/utils/builder/create_embed.rs
+++ b/src/utils/builder/create_embed.rs
@@ -197,6 +197,7 @@ impl CreateEmbedAuthor {
 }
 
 impl Default for CreateEmbedAuthor {
+    /// Creates a builder with no default values.
     fn default() -> CreateEmbedAuthor {
         CreateEmbedAuthor(ObjectBuilder::new())
     }
@@ -259,6 +260,7 @@ impl CreateEmbedFooter {
 }
 
 impl Default for CreateEmbedFooter {
+    /// Creates a builder with no default values.
     fn default() -> CreateEmbedFooter {
         CreateEmbedFooter(ObjectBuilder::new())
     }
@@ -294,6 +296,7 @@ impl CreateEmbedThumbnail {
 }
 
 impl Default for CreateEmbedThumbnail {
+    /// Creates a builder with no default values.
     fn default() -> CreateEmbedThumbnail {
         CreateEmbedThumbnail(ObjectBuilder::new())
     }
@@ -329,6 +332,7 @@ impl CreateEmbedVideo {
 }
 
 impl Default for CreateEmbedVideo {
+    /// Creates a builder with no default values.
     fn default() -> CreateEmbedVideo {
         CreateEmbedVideo(ObjectBuilder::new())
     }
diff --git a/src/utils/builder/create_invite.rs b/src/utils/builder/create_invite.rs
index 55cc1bd..c8e175a 100644
--- a/src/utils/builder/create_invite.rs
+++ b/src/utils/builder/create_invite.rs
@@ -65,6 +65,7 @@ impl CreateInvite {
 }
 
 impl Default for CreateInvite {
+    /// Creates a builder with default values, setting `validate` to `null`.
     fn default() -> CreateInvite {
         CreateInvite(ObjectBuilder::new().insert("validate", Value::Null))
     }
diff --git a/src/utils/builder/execute_webhook.rs b/src/utils/builder/execute_webhook.rs
index d2a14aa..a434057 100644
--- a/src/utils/builder/execute_webhook.rs
+++ b/src/utils/builder/execute_webhook.rs
@@ -10,7 +10,47 @@ use std::default::Default;
 /// Refer to the documentation for [`execute_webhook`] on restrictions with
 /// execution payloads and its fields.
 ///
+/// # Examples
+///
+/// Creating two embeds, and then sending them as part of the delivery
+/// payload of [`Webhook::execute`]:
+///
+/// ```rust,no_run
+/// use serenity::client::http;
+/// use serenity::model::Embed;
+/// use serenity::utils::Colour;
+///
+/// let id = 245037420704169985;
+/// let token = "ig5AO-wdVWpCBtUUMxmgsWryqgsW3DChbKYOINftJ4DCrUbnkedoYZD0VOH1QLr-S3sV";
+///
+/// let webhook = http::get_webhook_with_token(id, token)
+///     .expect("valid webhook");
+///
+/// let website = Embed::fake(|e| e
+///     .title("The Rust Language Website")
+///     .description("Rust is a systems programming language.")
+///     .colour(Colour::from_rgb(222, 165, 132)));
+///
+/// let resources = Embed::fake(|e| e
+///     .title("Rust Resources")
+///     .description("A few resources to help with learning Rust")
+///     .colour(0xDEA584)
+///     .field(|f| f
+///         .inline(false)
+///         .name("The Rust Book")
+///         .value("A comprehensive resource for all topics related to Rust"))
+///     .field(|f| f
+///         .inline(false)
+///         .name("Rust by Example")
+///         .value("A collection of Rust examples on topics, useable in-browser")));
+///
+/// let _ = webhook.execute(|w| w
+///     .content("Here's some information on Rust:")
+///     .embeds(vec![website, resources]));
+/// ```
+///
 /// [`Webhook`]: ../model/struct.Webhook.html
+/// [`Webhook::execute`]: ../../model/struct.Webhook.html#method.execute
 /// [`execute_webhook`]: ../client/http/fn.execute_webhook.html
 pub struct ExecuteWebhook(pub ObjectBuilder);
 
@@ -21,11 +61,28 @@ impl ExecuteWebhook {
     }
 
     /// Set the content of the message.
+    ///
+    /// Note that when setting at least one embed via [`embeds`], this may be
+    /// omitted.
+    ///
+    /// [`embeds`]: #method.embeds
     pub fn content(self, content: &str) -> Self {
         ExecuteWebhook(self.0.insert("content", content))
     }
 
-    // Set the embeds associated with the message.
+    /// Set the embeds associated with the message.
+    ///
+    /// This should be used in combination with [`Embed::fake`], creating one
+    /// or more fake embeds to send to the API.
+    ///
+    /// # Examples
+    ///
+    /// Refer to the [struct-level documentation] for an example on how to use
+    /// embeds.
+    ///
+    /// [`Embed::fake`]: ../../model/struct.Embed.html#method.fake
+    /// [`Webhook::execute`]: ../../model/struct.Webhook.html#method.execute
+    /// [struct-level documentation]: #examples
     pub fn embeds(self, embeds: Vec<Value>) -> Self {
         ExecuteWebhook(self.0.insert("embeds", embeds))
     }
@@ -46,9 +103,12 @@ 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
+    /// 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.rs won't be a part of it.
+    ///
+    /// [`Webhook`]: ../../model/struct.Webhook.html
+    /// [`tts`]: #method.tts
     fn default() -> ExecuteWebhook {
         ExecuteWebhook(ObjectBuilder::new().insert("tts", false))
     }
diff --git a/src/utils/builder/get_messages.rs b/src/utils/builder/get_messages.rs
index 4fdadff..d5088e8 100644
--- a/src/utils/builder/get_messages.rs
+++ b/src/utils/builder/get_messages.rs
@@ -75,6 +75,7 @@ impl GetMessages {
 }
 
 impl Default for GetMessages {
+    /// Creates a builder with no default values.
     fn default() -> GetMessages {
         GetMessages(BTreeMap::default())
     }
diff --git a/src/utils/colour.rs b/src/utils/colour.rs
index adaf1cc..de55df6 100644
--- a/src/utils/colour.rs
+++ b/src/utils/colour.rs
@@ -2,9 +2,10 @@ use std::default::Default;
 use ::internal::prelude::*;
 
 macro_rules! colour {
-    ($struct_:ident; $($name:ident, $val:expr;)*) => {
+    ($struct_:ident; $(#[$attr:meta] $name:ident, $val:expr;)*) => {
         impl $struct_ {
             $(
+                #[$attr]
                 pub fn $name() -> Colour {
                     Colour::new($val)
                 }
@@ -39,7 +40,7 @@ macro_rules! colour {
 ///
 /// Creating an instance with the [`dark_teal`] presets:
 ///
-/// ```rust,ignore
+/// ```rust
 /// use serenity::utils::Colour;
 ///
 /// let colour = Colour::dark_teal();
@@ -52,13 +53,28 @@ macro_rules! colour {
 /// [`get_g`]: #method.get_g
 #[derive(Clone, Copy, Debug)]
 pub struct Colour {
-    /// The raw inner integer value of this Colour. This is worked with to
-    /// generate values such as the red component value.
+    /// The raw inner 32-bit unsigned integer value of this Colour. This is
+    /// worked with to generate values such as the red component value.
     pub value: u32,
 }
 
 impl Colour {
     /// Generates a new Colour with the given integer value set.
+    ///
+    /// # Examples
+    ///
+    /// Create a new Colour, and then ensure that its inner value is equivilant
+    /// to a specific RGB value, retrieved via [`get_tuple`]:
+    ///
+    /// ```rust
+    /// use serenity::utils::Colour;
+    ///
+    /// let colour = Colour::new(6573123);
+    ///
+    /// assert_eq!(colour.get_tuple(), (100, 76, 67));
+    /// ```
+    ///
+    /// [`get_tuple`]: #method.get_tuple
     pub fn new(value: u32) -> Colour {
         Colour {
             value: value,
@@ -109,33 +125,112 @@ impl Colour {
     }
 
     /// Returns the red RGB component of this Colour.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use serenity::utils::Colour;
+    ///
+    /// assert_eq!(Colour::new(6573123).get_r(), 100);
+    /// ```
     pub fn get_r(&self) -> u8 {
         ((self.value >> 16) & 255) as u8
     }
 
     /// Returns the green RGB component of this Colour.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use serenity::utils::Colour;
+    ///
+    /// assert_eq!(Colour::new(6573123).get_g(), 76);
+    /// ```
     pub fn get_g(&self) -> u8 {
         ((self.value >> 8) & 255) as u8
     }
 
     /// Returns the blue RGB component of this Colour.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use serenity::utils::Colour;
+    ///
+    /// assert_eq!(Colour::new(6573123).get_b(), 67);
     pub fn get_b(&self) -> u8 {
         (self.value & 255) as u8
     }
 
     /// Returns a tuple of the red, green, and blue components of this Colour.
+    ///
+    /// This is equivilant to creating a tuple with the return values of
+    /// [`get_r`], [`get_g`], and [`get_b`].
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use serenity::utils::Colour;
+    ///
+    /// assert_eq!(Colour::new(6573123).get_tuple(), (100, 76, 67));
+    /// ```
+    ///
+    /// [`get_r`]: #method.get_r
+    /// [`get_g`]: #method.get_g
+    /// [`get_b`]: #method.get_b
     pub fn get_tuple(&self) -> (u8, u8, u8) {
         (self.get_r(), self.get_g(), self.get_b())
     }
 }
 
+impl From<i32> for Colour {
+    /// Constructs a Colour from a i32.
+    ///
+    /// This is used for functions that accept `Into<Colour>`.
+    ///
+    /// This is useful when providing hex values.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use serenity::utils::Colour;
+    ///
+    /// assert_eq!(Colour::from(0xDEA584).get_tuple(), (222, 165, 132));
+    /// ```
+    fn from(value: i32) -> Colour {
+        Colour::new(value as u32)
+    }
+}
+
 impl From<u32> for Colour {
+    /// Constructs a Colour from a u32.
+    ///
+    /// This is used for functions that accept `Into<Colour>`.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use serenity::utils::Colour;
+    ///
+    /// assert_eq!(Colour::from(6573123u32).get_r(), 100);
+    /// ```
     fn from(value: u32) -> Colour {
         Colour::new(value)
     }
 }
 
 impl From<u64> for Colour {
+    /// Constructs a Colour from a u32.
+    ///
+    /// This is used for functions that accept `Into<Colour>`.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use serenity::utils::Colour;
+    ///
+    /// assert_eq!(Colour::from(6573123u64).get_r(), 100);
+    /// ```
     fn from(value: u64) -> Colour {
         Colour::new(value as u32)
     }
@@ -143,28 +238,49 @@ impl From<u64> for Colour {
 
 colour! {
     Colour;
-    blue, 0x3498db;
+    /// Creates a new `Colour`, setting its RGB value to `(52, 152, 219)`.
+    blue, 0x3498DB;
+    /// Creates a new `Colour`, setting its RGB value to `(32, 102, 148)`.
     dark_blue, 0x206694;
-    dark_green, 0x1f8b4c;
-    dark_gold, 0xc27c0e;
-    dark_grey, 0x607d8b;
-    dark_magenta, 0xad1457;
-    dark_orange, 0xa84300;
-    dark_purple, 0x71368a;
-    dark_red, 0x992d22;
-    dark_teal, 0x11806a;
-    darker_grey, 0x546e7a;
-    gold, 0xf1c40f;
-    light_grey, 0x979c9f;
-    lighter_grey, 0x95a5a6;
-    magenta, 0xe91e63;
-    orange, 0xe67e22;
-    purple, 0x9b59b6;
-    red, 0xe74c3c;
-    teal, 0x1abc9c;
+    /// Creates a new `Colour`, setting its RGB value to `(31, 139, 76)`.
+    dark_green, 0x1F8B4C;
+    /// Creates a new `Colour`, setting its RGB value to `(194, 124, 14)`.
+    dark_gold, 0xC27C0E;
+    /// Creates a new `Colour`, setting its RGB value to `(96, 125, 139)`.
+    dark_grey, 0x607D8B;
+    /// Creates a new `Colour`, setting its RGB value to `(173, 20, 87)`.
+    dark_magenta, 0xAD1457;
+    /// Creates a new `Colour`, setting its RGB value to `(168, 67, 0)`.
+    dark_orange, 0xA84300;
+    /// Creates a new `Colour`, setting its RGB value to `(113, 54, 138)`.
+    dark_purple, 0x71368A;
+    /// Creates a new `Colour`, setting its RGB value to `(153, 45, 34)`.
+    dark_red, 0x992D22;
+    /// Creates a new `Colour`, setting its RGB value to `(17, 128, 106)`.
+    dark_teal, 0x11806A;
+    /// Creates a new `Colour`, setting its RGB value to `(84, 110, 122)`.
+    darker_grey, 0x546E7A;
+    /// Creates a new `Colour`, setting its RGB value to `(241, 196, 15)`.
+    gold, 0xF1C40F;
+    /// Creates a new `Colour`, setting its RGB value to `(151, 156, 159)`.
+    light_grey, 0x979C9F;
+    /// Creates a new `Colour`, setting its RGB value to `(149, 165, 166)`.
+    lighter_grey, 0x95A5A6;
+    /// Creates a new `Colour`, setting its RGB value to `(233, 30, 99)`.
+    magenta, 0xE91E63;
+    /// Creates a new `Colour`, setting its RGB value to `(230, 126, 34)`.
+    orange, 0xE67E22;
+    /// Creates a new `Colour`, setting its RGB value to `(155, 89, 182)`.
+    purple, 0x9B59B6;
+    /// Creates a new `Colour`, setting its RGB value to `(231, 76, 60)`.
+    red, 0xE74C3C;
+    /// Creates a new `Colour`, setting its RGB value to `(26, 188, 156)`.
+    teal, 0x1ABC9C;
 }
 
 impl Default for Colour {
+    /// Creates a default value for a `Colour`, setting the inner value to `0`.
+    /// This is equivilant to setting the RGB value to `(0, 0, 0)`.
     fn default() -> Colour {
         Colour {
             value: 0,
diff --git a/src/utils/message_builder.rs b/src/utils/message_builder.rs
index 7ba7717..a9a88ae 100644
--- a/src/utils/message_builder.rs
+++ b/src/utils/message_builder.rs
@@ -5,11 +5,12 @@ use ::model::{ChannelId, Emoji, Mentionable, RoleId, UserId};
 /// The Message Builder is an ergonomic utility to easily build a message,
 /// by adding text and mentioning mentionable structs.
 ///
-/// The finalized value can be accessed via `.build()` or the inner value.
+/// The finalized value can be accessed via [`build`] or the inner value.
 ///
 /// # Examples
 ///
-/// Build a message, mentioning a user and an emoji:
+/// Build a message, mentioning a [`user`] and an [`emoji`], and retrieving the
+/// value:
 ///
 /// ```rust,ignore
 /// use serenity::utils::MessageBuilder;
@@ -23,6 +24,10 @@ use ::model::{ChannelId, Emoji, Mentionable, RoleId, UserId};
 ///     .mention(emoji)
 ///     .build();
 /// ```
+///
+/// [`build`]: #method.build
+/// [`emoji`]: #method.emoji
+/// [`user`]: #method.user
 pub struct MessageBuilder(pub String);
 
 impl MessageBuilder {
@@ -31,20 +36,46 @@ impl MessageBuilder {
         MessageBuilder::default()
     }
 
-    /// Pulls the inner value out of the builder. This is equivilant to simply
-    /// retrieving the value.
+    /// Pulls the inner value out of the builder.
+    ///
+    /// # Examples
+    ///
+    /// This is equivilant to simply retrieving the tuple struct's first value:
+    ///
+    /// ```rust
+    /// use serenity::utils::MessageBuilder;
+    ///
+    /// let content = MessageBuilder::new().push("test").0;
+    ///
+    /// assert_eq!(content, "test");
+    /// ```
     pub fn build(self) -> String {
         self.0
     }
 
-    /// Mentions the channel in the built message.
+    /// Mentions the [`PublicChannel`] in the built message.
+    ///
+    /// This accepts anything that converts _into_ a [`ChannelId`]. Refer to
+    /// `ChannelId`'s documentation for more information.
+    ///
+    /// Refer to `ChannelId`'s [Display implementation] for more information on
+    /// how this is formatted.
+    ///
+    /// [`ChannelId`]: ../model/struct.ChannelId.html
+    /// [`PublicChannel`]: ../model/struct.PublicChannel.html
+    /// [Display implementation]: ../model/struct.ChannelId.html#method.fmt-1
     pub fn channel<C: Into<ChannelId>>(mut self, channel: C) -> Self {
         self.0.push_str(&format!("{}", channel.into()));
 
         self
     }
 
-    /// Uses and displays the given emoji in the built message.
+    /// Displays the given emoji in the built message.
+    ///
+    /// Refer to `Emoji`s [Display implementation] for more information on how
+    /// this is formatted.
+    ///
+    /// [Display implementation]: ../model/struct.Emoji.html#method.fmt
     pub fn emoji(mut self, emoji: Emoji) -> Self {
         self.0.push_str(&format!("{}", emoji));
 
@@ -65,6 +96,16 @@ impl MessageBuilder {
     /// Note that this does not mutate either the given data or the internal
     /// message content in anyway prior to appending the given content to the
     /// internal message.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use serenity::utils::MessageBuilder;
+    ///
+    /// let message = MessageBuilder::new().push("test");
+    ///
+    /// assert_eq!(message.push("ing").0, "testing");
+    /// ```
     pub fn push(mut self, content: &str) -> Self {
         self.0.push_str(content);
 
@@ -72,14 +113,34 @@ impl MessageBuilder {
     }
 
 
-    /// Mentions the role in the built message.
+    /// Mentions the [`Role`] in the built message.
+    ///
+    /// This accepts anything that converts _into_ a [`RoleId`]. Refer to
+    /// `RoleId`'s documentation for more information.
+    ///
+    /// Refer to `RoleId`'s [Display implementation] for more information on how
+    /// this is formatted.
+    ///
+    /// [`Role`]: ../model/struct.Role.html
+    /// [`RoleId`]: ../model/struct.RoleId.html
+    /// [Display implementation]: ../model/struct.RoleId.html#method.fmt-1
     pub fn role<R: Into<RoleId>>(mut self, role: R) -> Self {
         self.0.push_str(&format!("{}", role.into()));
 
         self
     }
 
-    /// Mentions the user in the built message.
+    /// Mentions the [`User`] in the built message.
+    ///
+    /// This accepts anything that converts _into_ a [`UserId`]. Refer to
+    /// `UserId`'s documentation for more information.
+    ///
+    /// Refer to `UserId`'s [Display implementation] for more information on how
+    /// this is formatted.
+    ///
+    /// [`User`]: ../model/struct.User.html
+    /// [`UserId`]: ../model/struct.UserId.html
+    /// [Display implementation]: ../model/struct.UserId.html#method.fmt-1
     pub fn user<U: Into<UserId>>(mut self, user: U) -> Self {
         self.0.push_str(&format!("{}", user.into()));
 
diff --git a/src/utils/mod.rs b/src/utils/mod.rs
index ccf7787..cb97a58 100644
--- a/src/utils/mod.rs
+++ b/src/utils/mod.rs
@@ -93,14 +93,37 @@ pub fn into_array(value: Value) -> Result<Vec<Value>> {
 /// Retrieves the "code" part of an [invite][`RichInvite`] out of a URL.
 ///
 /// # Examples
-/// Retrieving the code from the URL `https://discord.gg/0cDvIgU2voY8RSYL`:
 ///
-/// ```rust,ignore
+/// Three formats of codes are supported:
+///
+/// 1. Retrieving the code from the URL `"https://discord.gg/0cDvIgU2voY8RSYL"`:
+///
+/// ```rust
 /// use serenity::utils;
 ///
 /// let url = "https://discord.gg/0cDvIgU2voY8RSYL";
 ///
-/// assert!(utils::parse_invite(url) == "0cDvIgU2voY8RSYL");
+/// assert_eq!(utils::parse_invite(url), "0cDvIgU2voY8RSYL");
+/// ```
+///
+/// 2. Retrieving the code from the URL `"http://discord.gg/0cDvIgU2voY8RSYL"`:
+///
+/// ```rust
+/// use serenity::utils;
+///
+/// let url = "http://discord.gg/0cDvIgU2voY8RSYL";
+///
+/// assert_eq!(utils::parse_invite(url), "0cDvIgU2voY8RSYL");
+/// ```
+///
+/// 3. Retrieving the code from the URL `"discord.gg/0cDvIgU2voY8RSYL"`:
+///
+/// ```rust
+/// use serenity::utils;
+///
+/// let url = "discord.gg/0cDvIgU2voY8RSYL";
+///
+/// assert_eq!(utils::parse_invite(url), "0cDvIgU2voY8RSYL");
 /// ```
 ///
 /// [`RichInvite`]: ../model/struct.RichInvite.html
@@ -124,7 +147,7 @@ pub fn parse_invite(code: &str) -> &str {
 ///
 /// Reads an image located at `./cat.png` into a base64-encoded string:
 ///
-/// ```rust,ignore
+/// ```rust,no_run
 /// use serenity::utils;
 ///
 /// let image = match utils::read_image("./cat.png") {