Index: colors.py
===================================================================
--- colors.py	(revision 8565)
+++ colors.py	(working copy)
@@ -1002,20 +1002,38 @@
     convert rgb values in a numpy array to hsv values
     input and output arrays should have shape (M,N,3)
     """
+    # More info and explanation can be found at
+    # http://en.wikipedia.org/wiki/HSL_and_HSV#Hue_and_chroma
+    # This method produces NaNs for the hue of neutral colors.
     out = np.empty_like(arr)
     arr_max = arr.max(-1)
+
+    # delta is a.k.a. chroma ('C')
     delta = arr.ptp(-1)
+
+    # Calculating saturation
     s = delta / arr_max
+    # Neutral colors given a saturation of zero
     s[delta==0] = 0
-    # red is max
+
+    # where max is red ('R')
     idx = (arr[:,:,0] == arr_max)
+    # (G - B) / C
     out[idx, 0] = (arr[idx, 1] - arr[idx, 2]) / delta[idx]
-    # green is max
+
+    # where max is green ('G')
     idx = (arr[:,:,1] == arr_max)
+    # 2 + (B - R) / C
     out[idx, 0] = 2. + (arr[idx, 2] - arr[idx, 0] ) / delta[idx]
-    # blue is max
+
+    # where max is blue ('B')
     idx = (arr[:,:,2] == arr_max)
+    # 4 + (R - G) / C
     out[idx, 0] = 4. + (arr[idx, 0] - arr[idx, 1] ) / delta[idx]
+
+    # Note, 6 is a significant number because the hue is
+    # segmented into six natural color combinations of rgb
+    # (3! = 3 * 2 * 1 = 6)
     out[:,:,0] = (out[:,:,0]/6.0) % 1.0
     out[:,:,1] = s
     out[:,:,2] = arr_max
@@ -1026,6 +1044,9 @@
     convert hsv values in a numpy array to rgb values
     both input and output arrays have shape (M,N,3)
     """
+    # Note, 6 is a significant number because the hue is
+    # segmented into six natural color combinations of rgb
+    # (3! = 3 * 2 * 1 = 6)
     h = hsv[:,:,0]; s = hsv[:,:,1]; v = hsv[:,:,2]
     r = np.empty_like(h); g = np.empty_like(h); b = np.empty_like(h)
     i = (h*6.0).astype(np.int)