Comments ahoy

src/color/hsv.rs

@@ -33,13 +33,15 @@ impl<T:FloatChannel> HSV<T> {
 }
 
 impl<T:FloatChannel> Color<T> for HSV<T> {
+    /// Clamps the components of the color to the range `(lo,hi)`.
     #[inline]
     pub fn clamp(&self, lo: T, hi: T) -> HSV<T> {
-        HSV::new((*self).h.clamp(&lo, &hi),
+        HSV::new((*self).h.clamp(&lo, &hi), // Should the hue component be clamped?
                  (*self).s.clamp(&lo, &hi),
                  (*self).v.clamp(&lo, &hi))
     }
 
+    /// Inverts the color.
     #[inline]
     pub fn inverse(&self) -> HSV<T> {
         HSV::new((*self).h.invert_degrees(),
@@ -49,6 +51,8 @@ impl<T:FloatChannel> Color<T> for HSV<T> {
 }
 
 impl<T:FloatChannel> FloatColor<T> for HSV<T> {
+    /// Normalizes the components of the color. Modulo `360` is applied to the
+    /// `h` component, and `s` and `v` are clamped to the range `(0,1)`.
     #[inline]
     pub fn normalize(&self) -> HSV<T> {
         HSV::new((*self).h.normalize_degrees(),
@@ -142,14 +146,16 @@ impl<T:FloatChannel> HSVA<T> {
 }
 
 impl<T:FloatChannel> Color<T> for HSVA<T> {
+    /// Clamps the components of the color to the range `(lo,hi)`.
     #[inline]
     pub fn clamp(&self, lo: T, hi: T) -> HSVA<T> {
-        HSVA::new((*self).h.clamp(&lo, &hi),
+        HSVA::new((*self).h.clamp(&lo, &hi),    // Should the hue component be clamped?
                   (*self).s.clamp(&lo, &hi),
                   (*self).v.clamp(&lo, &hi),
                   (*self).a.clamp(&lo, &hi))
     }
 
+    /// Inverts the color.
     #[inline]
     pub fn inverse(&self) -> HSVA<T> {
         HSVA::new((*self).h.invert_degrees(),
@@ -160,6 +166,8 @@ impl<T:FloatChannel> Color<T> for HSVA<T> {
 }
 
 impl<T:FloatChannel> FloatColor<T> for HSVA<T> {
+    /// Normalizes the components of the color. Modulo `360` is applied to the
+    /// `h` component, and `s`, `v` and `a` are clamped to the range `(0,1)`.
     #[inline]
     pub fn normalize(&self) -> HSVA<T> {
         HSVA::new((*self).h.normalize_degrees(),

src/color/rgb.rs

@@ -34,6 +34,7 @@ impl<T:Channel> RGB<T> {
 }
 
 impl<T:Channel> Color<T> for RGB<T> {
+    /// Clamps the components of the color to the range `(lo,hi)`.
     #[inline]
     pub fn clamp(&self, lo: T, hi: T) -> RGB<T> {
         RGB::new((*self).r.clamp(&lo, &hi),
@@ -41,6 +42,7 @@ impl<T:Channel> Color<T> for RGB<T> {
                  (*self).b.clamp(&lo, &hi))
     }
 
+    /// Inverts the color.
     #[inline]
     pub fn inverse(&self) -> RGB<T> {
         RGB::new((*self).r.invert_channel(),
@@ -50,6 +52,7 @@ impl<T:Channel> Color<T> for RGB<T> {
 }
 
 impl<T:FloatChannel> FloatColor<T> for RGB<T> {
+    /// Normalizes the components of the color by clamping them to the range `(0,1)`.
     #[inline]
     pub fn normalize(&self) -> RGB<T> {
         RGB::new((*self).r.clamp(&zero!(T), &one!(T)),
@@ -140,6 +143,7 @@ impl<T:Channel> RGBA<T> {
 }
 
 impl<T:Channel> Color<T> for RGBA<T> {
+    /// Clamps the components of the color to the range `(lo,hi)`.
     #[inline]
     pub fn clamp(&self, lo: T, hi: T) -> RGBA<T> {
         RGBA::new((*self).r.clamp(&lo, &hi),
@@ -148,6 +152,7 @@ impl<T:Channel> Color<T> for RGBA<T> {
                   (*self).a.clamp(&lo, &hi))
     }
 
+    /// Inverts the color.
     #[inline]
     pub fn inverse(&self) -> RGBA<T> {
         RGBA::new((*self).r.invert_channel(),
@@ -158,6 +163,7 @@ impl<T:Channel> Color<T> for RGBA<T> {
 }
 
 impl<T:FloatChannel> FloatColor<T> for RGBA<T> {
+    /// Normalizes the components of the color by clamping them to the range `(0,1)`.
     #[inline]
     pub fn normalize(&self) -> RGBA<T> {
         RGBA::new((*self).r.clamp(&zero!(T), &one!(T)),

src/color/ycbcr.rs

@@ -13,6 +13,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// http://en.wikipedia.org/wiki/YCbCr
+
 #[deriving(Clone, Eq)]
 pub struct YCbCr<T> { y: T, cb: T, cr: T }