[gtkmm] Gdk::RGBA, Color: Fix set_hsl(), improve documentation

[Kjell Ahlstedt <kjellahl src gnome org>]

commit cd5137157e874e5a59661b918aa691d2502a72e8
Author: Kjell Ahlstedt <kjell ahlstedt bredband net>
Date:   Thu Dec 12 15:30:33 2013 +0100

    Gdk::RGBA, Color: Fix set_hsl(), improve documentation
    
    * gdk/src/color.ccg:
    * gdk/src/rgba.ccg: Fix the conversion from HSL to RGB color in set_hsl().
    * gdk/src/color.hg:
    * gdk/src/rgba.hg: Add docs of set_hsv() and set_hsl(). Change 'percentage'
    to 'fraction' in docs. (The range is not 0..100, it's 0..1.)
    Bug #720258.

 gdk/src/color.ccg |   33 +++++++++++++++++--
 gdk/src/color.hg  |   45 ++++++++++++++++++---------
 gdk/src/rgba.ccg  |   33 +++++++++++++++++--
 gdk/src/rgba.hg   |   88 +++++++++++++++++++++++++++++++---------------------
 4 files changed, 140 insertions(+), 59 deletions(-)
---
diff --git a/gdk/src/color.ccg b/gdk/src/color.ccg
index 504a25e..7390786 100644
--- a/gdk/src/color.ccg
+++ b/gdk/src/color.ccg
@@ -61,7 +61,18 @@ void Color::set_rgb_p(double red_, double green_, double blue_)
 
 void Color::set_hsv(double h, double s, double v)
 {
-  //TODO: Comments/Documentation. I have no idea what this code does. murrayc.
+  // The HSV color space is described in a long Wikipedia article,
+  // http://en.wikipedia.org/wiki/HSV_color_space
+  // The following conversion from HSV to RGB is equivalent to the conversion
+  // shown in Wikipedia. The following relations hold between the Wikipedia
+  // equations (uppercase letters) and the equations used here (lowercase letters):
+  //
+  // h = H' (after division of h by 60 degrees)
+  // p = V - C = m (m from Wikipedia), thus v = C + m
+  // When i is odd:  X + m = V - C * abs(H' mod 2 - 1)
+  //                       = v - vs * (h - i) = q
+  // When i is even: X + m = V - C * abs(H' mod 2 - 1)
+  //                       = v - vs * (1 - (h - i)) = t
 
   h /= 60.0;
   int i = (int)h;
@@ -93,7 +104,18 @@ void Color::set_hsv(double h, double s, double v)
 
 void Color::set_hsl(double h, double s, double l)
 {
-  //TODO: Comments/Documentation. I have no idea what this code does. murrayc.
+  // The HSL color space is described in a long Wikipedia article,
+  // http://en.wikipedia.org/wiki/HSV_color_space
+  // The following conversion from HSL to RGB is equivalent to the conversion
+  // shown in Wikipedia. The following relations hold between the Wikipedia
+  // equations (uppercase letters) and the equations used here (lowercase letters):
+  //
+  // 6*h = H' (after division of h by 360 degrees)
+  // t2 = C + m (m from Wikipedia)
+  // t1 = m
+  //
+  // The conversion algorithm used here is shown at
+  // http://www.w3.org/TR/css3-color/#hsl-color
 
   if(s == 0.0)
     set_grey_p(l);
@@ -106,9 +128,12 @@ void Color::set_hsl(double h, double s, double l)
     double tr = h + 1.0/3.0;
     double tg = h;
     double tb = h - 1.0/3.0;
-    if (tb < 0) tb += 1.0;
+    if (tr > 1.0) tr -= 1.0;
+    if (tb < 0.0) tb += 1.0;
 
-    double r = 0.0, g = 0.0, b = 0.0;
+    double r = t1;
+    double g = t1;
+    double b = t1;
 
     if (tr < 1.0/6.0)
       r = t1 +(t2-t1) * 6 * tr;
diff --git a/gdk/src/color.hg b/gdk/src/color.hg
index eca9e5a..b1895e1 100644
--- a/gdk/src/color.hg
+++ b/gdk/src/color.hg
@@ -32,10 +32,10 @@ namespace Gdk
 
 /** Gdk::Color is used to describe an allocated or unallocated color.
  * It contains the following data:
- *   pixel: For allocated colors, the value used to draw this color on the screen.
- *   red: The red component of the color. This is a value between 0 and 65535, with 65535 indicating full 
intensitiy.
- *   green: The green component of the color.
- *   blue: The blue component of the color.
+ * - pixel: For allocated colors, the value used to draw this color on the screen.
+ * - red: The red component of the color. This is a value between 0 and 65535, with 65535 indicating full 
intensitiy.
+ * - green: The green component of the color.
+ * - blue: The blue component of the color.
  *
  * @deprecated Use Gdk::RGBA instead.
  */
@@ -55,7 +55,7 @@ public:
   /** Instantiate a new Gdk::Color.
    * The text string can be in any of the forms accepted by XParseColor; these include names for a color 
from rgb.txt,
    * such as DarkSlateGray, or a hex specification such as 305050.
-   * @param value the string specifying the color..
+   * @param value the string specifying the color.
    */
   explicit Color(const Glib::ustring& value);
 
@@ -63,6 +63,10 @@ public:
    * @param value The value to be used for the red, green, and blue components.
    */
   void set_grey(gushort value);
+
+  /** Set a grey color, by using the same value for all color components.
+   * @param g The value to be used for the red, green, and blue components, as a fraction.
+   */
   void set_grey_p(double g);
 
   /** Set the color, by specifying red, green, and blue color component values.
@@ -72,14 +76,25 @@ public:
    */
   void set_rgb(gushort red_, gushort green_, gushort blue_);
 
-  /** Set the color, by specifying red, green, and blue color component values, as percentages.
-   * @param red_ The red component of the color, as a percentage.
-   * @param green_ The green component of the color, as a percentage.
-   * @param blue_ The blue component of the color, as a percentage.
+  /** Set the color, by specifying red, green, and blue color component values, as fractions.
+   * @param red_ The red component of the color, as a fraction.
+   * @param green_ The green component of the color, as a fraction.
+   * @param blue_ The blue component of the color, as a fraction.
    */
   void set_rgb_p(double red_, double green_, double blue_);
 
+  /** Set the color, by specifying hue, saturation, and value (brightness).
+   * @param h Hue, in the range 0..360 degrees.
+   * @param s Saturation, in the range 0..1.
+   * @param v Value (a.k.a. brightness), in the range 0..1.
+   */
   void set_hsv(double h, double s, double v);
+
+  /** Set the color, by specifying hue, saturation, and lightness.
+   * @param h Hue, in the range 0..360 degrees.
+   * @param s Saturation, in the range 0..1.
+   * @param l Lightness, in the range 0..1.
+   */
   void set_hsl(double h, double s, double l);
 
   /** Parses a textual specification of a color and fills in the red, green, and blue values.
@@ -126,18 +141,18 @@ public:
    */
   guint get_pixel() const;
 
-  /** Get the red component of the color, as a percentage.
-   * @result The red component of the color, as a percentage.
+  /** Get the red component of the color, as a fraction.
+   * @result The red component of the color, as a fraction.
    */
   double get_red_p() const;
 
-  /** Get the green component of the color, as a percentage.
-   * @result The green component of the color, as a percentage.
+  /** Get the green component of the color, as a fraction.
+   * @result The green component of the color, as a fraction.
    */
   double get_green_p() const;
 
-  /** Get the blue component of the color, as a percentage.
-   * @result The blue component of the color, as a percentage.
+  /** Get the blue component of the color, as a fraction.
+   * @result The blue component of the color, as a fraction.
    */
   double get_blue_p() const;
 
diff --git a/gdk/src/rgba.ccg b/gdk/src/rgba.ccg
index 703b03a..2ea3003 100644
--- a/gdk/src/rgba.ccg
+++ b/gdk/src/rgba.ccg
@@ -67,7 +67,18 @@ void RGBA::set_rgba(double red_, double green_, double blue_, double alpha_)
 
 void RGBA::set_hsv(double h, double s, double v)
 {
-  //TODO: Comments/Documentation. I have no idea what this code does. murrayc.
+  // The HSV color space is described in a long Wikipedia article,
+  // http://en.wikipedia.org/wiki/HSV_color_space
+  // The following conversion from HSV to RGB is equivalent to the conversion
+  // shown in Wikipedia. The following relations hold between the Wikipedia
+  // equations (uppercase letters) and the equations used here (lowercase letters):
+  //
+  // h = H' (after division of h by 60 degrees)
+  // p = V - C = m (m from Wikipedia), thus v = C + m
+  // When i is odd:  X + m = V - C * abs(H' mod 2 - 1)
+  //                       = v - vs * (h - i) = q
+  // When i is even: X + m = V - C * abs(H' mod 2 - 1)
+  //                       = v - vs * (1 - (h - i)) = t
 
   h /= 60.0;
   int i = (int)h;
@@ -99,7 +110,18 @@ void RGBA::set_hsv(double h, double s, double v)
 
 void RGBA::set_hsl(double h, double s, double l)
 {
-  //TODO: Comments/Documentation. I have no idea what this code does. murrayc.
+  // The HSL color space is described in a long Wikipedia article,
+  // http://en.wikipedia.org/wiki/HSV_color_space
+  // The following conversion from HSL to RGB is equivalent to the conversion
+  // shown in Wikipedia. The following relations hold between the Wikipedia
+  // equations (uppercase letters) and the equations used here (lowercase letters):
+  //
+  // 6*h = H' (after division of h by 360 degrees)
+  // t2 = C + m (m from Wikipedia)
+  // t1 = m
+  //
+  // The conversion algorithm used here is shown at
+  // http://www.w3.org/TR/css3-color/#hsl-color
 
   if(s == 0.0)
     set_grey(l);
@@ -112,9 +134,12 @@ void RGBA::set_hsl(double h, double s, double l)
     double tr = h + 1.0/3.0;
     double tg = h;
     double tb = h - 1.0/3.0;
-    if (tb < 0) tb += 1.0;
+    if (tr > 1.0) tr -= 1.0;
+    if (tb < 0.0) tb += 1.0;
 
-    double r = 0.0, g = 0.0, b = 0.0;
+    double r = t1;
+    double g = t1;
+    double b = t1;
 
     if (tr < 1.0/6.0)
       r = t1 +(t2-t1) * 6 * tr;
diff --git a/gdk/src/rgba.hg b/gdk/src/rgba.hg
index 86b1424..c6c5942 100644
--- a/gdk/src/rgba.hg
+++ b/gdk/src/rgba.hg
@@ -46,118 +46,134 @@ public:
   /** Instantiate a new Gdk::RGBA.
    * The text string can be in any of the forms accepted by XParseRGBA; these include names for a color from 
rgb.txt,
    * such as DarkSlateGray, or a hex specification such as 305050.
-   * @param value the string specifying the color..
+   * @param value the string specifying the color.
    */
   explicit RGBA(const Glib::ustring& value);
   _IGNORE(gdk_rgba_parse)
 
   /** Set a grey color, by using the same value for all color components.
-   * @param value The value to be used for the red, green, and blue components.
-   * @param alpha The alpha component of the color.
+   * @param value The value to be used for the red, green, and blue components, in the range 0..65535.
+   * @param alpha The alpha component of the color, in the range 0..65535.
    */
   void set_grey_u(gushort value, gushort alpha = 65535);
+
+  /** Set a grey color, by using the same value for all color components.
+   * @param g The value to be used for the red, green, and blue components, as a fraction.
+   * @param alpha The alpha component of the color, as a fraction.
+   */
   void set_grey(double g, double alpha = 1.0);
 
   /** Set the color, by specifying red, green, and blue color component values.
-   * @param red_ The red component of the color.
-   * @param green_ The green component of the color.
-   * @param blue_ The blue component of the color.
-   * @param alpha_ The alpha component of the color.
+   * @param red_ The red component of the color, in the range 0..65535.
+   * @param green_ The green component of the color, in the range 0..65535.
+   * @param blue_ The blue component of the color, in the range 0..65535.
+   * @param alpha_ The alpha component of the color, in the range 0..65535.
    */
   void set_rgba_u(gushort red_, gushort green_, gushort blue_, gushort alpha_ = 65535);
 
-  /** Set the color, by specifying red, green, and blue color component values, as percentages.
-   * @param red_ The red component of the color, as a percentage.
-   * @param green_ The green component of the color, as a percentage.
-   * @param blue_ The blue component of the color, as a percentage.
-   * @param alpha_ The alpha component of the color, as a percentage.
+  /** Set the color, by specifying red, green, and blue color component values, as fractions.
+   * @param red_ The red component of the color, as a fraction.
+   * @param green_ The green component of the color, as a fraction.
+   * @param blue_ The blue component of the color, as a fraction.
+   * @param alpha_ The alpha component of the color, as a fraction.
    */
   void set_rgba(double red_, double green_, double blue_, double alpha_ = 1.0);
 
   //TODO: Add alpha parameter?
+  /** Set the color, by specifying hue, saturation, and value (brightness).
+   * @param h Hue, in the range 0..360 degrees.
+   * @param s Saturation, in the range 0..1.
+   * @param v Value (a.k.a. brightness), in the range 0..1.
+   */
   void set_hsv(double h, double s, double v);
+
+  /** Set the color, by specifying hue, saturation, and lightness.
+   * @param h Hue, in the range 0..360 degrees.
+   * @param s Saturation, in the range 0..1.
+   * @param l Lightness, in the range 0..1.
+   */
   void set_hsl(double h, double s, double l);
 
   _WRAP_METHOD(bool set(const Glib::ustring& spec), gdk_rgba_parse)
 
   /** Get the red component of the color.
-   * @result The red component of the color.
+   * @result The red component of the color, in the range 0..65535.
    */
   gushort get_red_u() const;
 
   /** Get the green component of the color.
-   * @result The green component of the color.
+   * @result The green component of the color, in the range 0..65535.
    */
   gushort get_green_u() const;
 
   /** Get the blue component of the color.
-   * @result The blue component of the color.
+   * @result The blue component of the color, in the range 0..65535.
    */
   gushort get_blue_u() const;
 
   /** Get the alpha component of the color.
-   * @result The alpha component of the color.
+   * @result The alpha component of the color, in the range 0..65535.
    */
   gushort get_alpha_u() const;
 
   /** Set the red component of the color.
-   * @param value The red component of the color.
+   * @param value The red component of the color, in the range 0..65535.
    */
   void set_red_u(gushort value);
 
   /** Set the green component of the color.
-   * @param value The green component of the color.
+   * @param value The green component of the color, in the range 0..65535.
    */
   void set_green_u(gushort value);
 
   /** Set the blue component of the color.
-   * @param value The blue component of the color.
+   * @param value The blue component of the color, in the range 0..65535.
    */
   void set_blue_u(gushort value);
 
   /** Set the alpha component of the color.
-   * @param value The alpha component of the color.
+   * @param value The alpha component of the color, in the range 0..65535.
    */
   void set_alpha_u(gushort value);
 
 
-  /** Get the red component of the color, as a percentage.
-   * @result The red component of the color, as a percentage.
+  /** Get the red component of the color, as a fraction.
+   * @result The red component of the color, as a fraction.
    */
   double get_red() const;
 
-  /** Get the green component of the color, as a percentage.
-   * @result The green component of the color, as a percentage.
+  /** Get the green component of the color, as a fraction.
+   * @result The green component of the color, as a fraction.
    */
   double get_green() const;
 
-  /** Get the blue component of the color, as a percentage.
-   * @result The blue component of the color, as a percentage.
+  /** Get the blue component of the color, as a fraction.
+   * @result The blue component of the color, as a fraction.
    */
   double get_blue() const;
 
-  /** Get the alpha component of the color, as a percentage.
-   * @result The alpha component of the color, as a percentage.
+  /** Get the alpha component of the color, as a fraction.
+   * @result The alpha component of the color, as a fraction.
    */
   double get_alpha() const;
 
-  /** Set the red component of the color, as a percentage.
-   * @param value The red component of the color.
+  /** Set the red component of the color, as a fraction.
+   * @param value The red component of the color, as a fraction.
    */
   void set_red(double value);
 
-  /** Set the green component of the color, as a percentage.
-   * @param value The green component of the color.
+  /** Set the green component of the color, as a fraction.
+   * @param value The green component of the color, as a fraction.
    */
   void set_green(double value);
 
-  /** Set the blue component of the color, as a percentage.
-   * @param value The blue component of the color.
+  /** Set the blue component of the color, as a fraction.
+   * @param value The blue component of the color, as a fraction.
    */
   void set_blue(double value);
 
-  /** Set the alpha component of the color, as a percentage.
-   * @param value The alpha component of the color.
+  /** Set the alpha component of the color, as a fraction.
+   * @param value The alpha component of the color, as a fraction.
    */
   void set_alpha(double value);