From 404fc72cb568ff0de2ce897b4a5a10d0b323f091 Mon Sep 17 00:00:00 2001
From: Napen123 <napen123@gmail.com>
Date: Sat, 6 Feb 2021 15:09:48 -0700
Subject: [PATCH] docs: Document the Color type in the swf crate

---
 swf/src/types.rs | 50 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/swf/src/types.rs b/swf/src/types.rs
index 4290034cf..c6f046a9f 100644
--- a/swf/src/types.rs
+++ b/swf/src/types.rs
@@ -241,15 +241,42 @@ pub struct Rectangle {
     pub y_max: Twips,
 }
 
+/// An RGBA (red, green, blue, alpha) color.
+///
+/// All components are stored as [`u8`] and have a color range of 0-255.
 #[derive(Debug, PartialEq, Clone)]
 pub struct Color {
+    /// The red component value.
     pub r: u8,
+
+    /// The green component value.
     pub g: u8,
+
+    /// The blue component value.
     pub b: u8,
+
+    /// The alpha component value.
     pub a: u8,
 }
 
 impl Color {
+    /// Creates a `Color` from a 32-bit `rgb` value and an `alpha` value.
+    ///
+    /// The byte-ordering of the 32-bit `rgb` value is XXRRGGBB.
+    /// The most significant byte, represented by XX, is ignored;
+    /// the `alpha` value is provided separately.
+    /// This is followed by the the red (RR), green (GG), and blue (BB) components values,
+    /// respectively.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use swf::Color;
+    ///
+    /// let red = Color::from_rgb(0xFF0000, 255);
+    /// let green = Color::from_rgb(0x00FF00, 255);
+    /// let blue = Color::from_rgb(0x0000FF, 255);
+    /// ```
     pub fn from_rgb(rgb: u32, alpha: u8) -> Self {
         Self {
             r: ((rgb & 0xFF_0000) >> 16) as u8,
@@ -258,6 +285,29 @@ impl Color {
             a: alpha,
         }
     }
+
+    /// Converts the color to a 32-bit RGB value.
+    ///
+    /// The alpha value does not get stored.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    /// ```rust
+    /// use swf::Color;
+    ///
+    /// let color = Color::from_rgb(0xFF00FF, 255);
+    /// assert_eq!(color.to_rgb(), 0xFF00FF);
+    /// ```
+    ///
+    /// Alpha values do not get stored:
+    /// ```rust
+    /// use swf::Color;
+    ///
+    /// let color1 = Color::from_rgb(0xFF00FF, 255);
+    /// let color2 = Color::from_rgb(0xFF00FF, 0);
+    /// assert_eq!(color1.to_rgb(), color2.to_rgb());
+    /// ```
     pub fn to_rgb(&self) -> u32 {
         ((self.r as u32) << 16) | ((self.g as u32) << 8) | (self.b as u32)
     }