A bit of docs

1 files changed, 138 insertions, 22 deletions

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,