[gimp/soc-2010-cage] libgimpcolor: fix most gtk-doc warnings

[Michael Muré <mmure src gnome org>]

commit 4686b9d9ba65793ec74b8f317ebae0bc12436bb1
Author: Michael Natterer <mitch gimp org>
Date:   Tue Jun 29 20:08:39 2010 +0200

    libgimpcolor: fix most gtk-doc warnings

 libgimpcolor/gimpadaptivesupersample.c |    2 +-
 libgimpcolor/gimpbilinear.c            |    2 +-
 libgimpcolor/gimpcmyk.c                |    2 +-
 libgimpcolor/gimpcolormanaged.c        |    2 +-
 libgimpcolor/gimpcolorspace.c          |    2 +-
 libgimpcolor/gimpcolortypes.h          |   43 +++++++++++++++++++++++++++
 libgimpcolor/gimphsv.c                 |    2 +-
 libgimpcolor/gimprgb.c                 |   50 ++++++++++++++++----------------
 8 files changed, 74 insertions(+), 31 deletions(-)
---
diff --git a/libgimpcolor/gimpadaptivesupersample.c b/libgimpcolor/gimpadaptivesupersample.c
index 631f34e..e258978 100644
--- a/libgimpcolor/gimpadaptivesupersample.c
+++ b/libgimpcolor/gimpadaptivesupersample.c
@@ -29,7 +29,7 @@
 
 
 /**
- * SECTION: GimpAdaptiveSupersample
+ * SECTION: gimpadaptivesupersample
  * @title: GimpAdaptiveSupersample
  * @short_description: Functions to perform adaptive supersampling on
  *                     an area.
diff --git a/libgimpcolor/gimpbilinear.c b/libgimpcolor/gimpbilinear.c
index c901d26..3546336 100644
--- a/libgimpcolor/gimpbilinear.c
+++ b/libgimpcolor/gimpbilinear.c
@@ -28,7 +28,7 @@
 
 
 /**
- * SECTION: GimpBilinear
+ * SECTION: gimpbilinear
  * @title: GimpBilinear
  * @short_description: Utility functions for bilinear interpolation.
  *
diff --git a/libgimpcolor/gimpcmyk.c b/libgimpcolor/gimpcmyk.c
index 471cdba..c06e012 100644
--- a/libgimpcolor/gimpcmyk.c
+++ b/libgimpcolor/gimpcmyk.c
@@ -28,7 +28,7 @@
 
 
 /**
- * SECTION: GimpCMYK
+ * SECTION: gimpcmyk
  * @title: GimpCMYK
  * @short_description: Definitions and Functions relating to CMYK colors.
  *
diff --git a/libgimpcolor/gimpcolormanaged.c b/libgimpcolor/gimpcolormanaged.c
index fcba9fb..6299643 100644
--- a/libgimpcolor/gimpcolormanaged.c
+++ b/libgimpcolor/gimpcolormanaged.c
@@ -29,7 +29,7 @@
 
 
 /**
- * SECTION: GimpColorManaged
+ * SECTION: gimpcolormanaged
  * @title: GimpColorManaged
  * @short_description: An interface dealing with color profiles.
  *
diff --git a/libgimpcolor/gimpcolorspace.c b/libgimpcolor/gimpcolorspace.c
index 98e8277..b601b53 100644
--- a/libgimpcolor/gimpcolorspace.c
+++ b/libgimpcolor/gimpcolorspace.c
@@ -31,7 +31,7 @@
 
 
 /**
- * SECTION: GimpColorSpace
+ * SECTION: gimpcolorspace
  * @title: GimpColorSpace
  * @short_description: Utility functions which convert colors between
  *                     different color models.
diff --git a/libgimpcolor/gimpcolortypes.h b/libgimpcolor/gimpcolortypes.h
index b633369..e2f5aac 100644
--- a/libgimpcolor/gimpcolortypes.h
+++ b/libgimpcolor/gimpcolortypes.h
@@ -35,21 +35,64 @@ typedef struct _GimpHSV  GimpHSV;
 typedef struct _GimpHSL  GimpHSL;
 typedef struct _GimpCMYK GimpCMYK;
 
+/**
+ * GimpRGB:
+ * @r: the red component
+ * @g: the green component
+ * @b: the blue component
+ * @a: the alpha component
+ *
+ * Used to keep RGB and RGBA colors. All components are in a range of
+ * [0.0..1.0].
+ **/
 struct _GimpRGB
 {
   gdouble r, g, b, a;
 };
 
+/**
+ * GimpHSV:
+ * @h: the hue component
+ * @s: the saturation component
+ * @v: the value component
+ * @a: the alpha component
+ *
+ * Used to keep HSV and HSVA colors. All components are in a range of
+ * [0.0..1.0].
+ **/
 struct _GimpHSV
 {
   gdouble h, s, v, a;
 };
 
+/**
+ * GimpHSL:
+ * @h: the hue component
+ * @s: the saturation component
+ * @l: the lightness component
+ * @a: the alpha component
+ *
+ * Used to keep HSL and HSLA colors. All components are in a range of
+ * [0.0..1.0].
+ **/
 struct _GimpHSL
 {
   gdouble h, s, l, a;
 };
 
+/**
+ * GimpCMYK:
+ * @c: the cyan component
+ * @m: the magenta component
+ * @y: the yellow component
+ * @k: the black component
+ * @a: the alpha component
+ *
+ * Used to keep CMYK and CMYKA colors. All components are in a range
+ * of [0.0..1.0]. An alpha value is somewhat useless in the CMYK
+ * colorspace, but we keep one around anyway so color conversions
+ * going to CMYK and back can preserve alpha.
+ **/
 struct _GimpCMYK
 {
   gdouble c, m, y, k, a;
diff --git a/libgimpcolor/gimphsv.c b/libgimpcolor/gimphsv.c
index 12dfde3..95ee362 100644
--- a/libgimpcolor/gimphsv.c
+++ b/libgimpcolor/gimphsv.c
@@ -26,7 +26,7 @@
 
 
 /**
- * SECTION: GimpHSV
+ * SECTION: gimphsv
  * @title: GimpHSV
  * @short_description: Definitions and Functions relating to HSV colors.
  *
diff --git a/libgimpcolor/gimprgb.c b/libgimpcolor/gimprgb.c
index a26d7bf..329c107 100644
--- a/libgimpcolor/gimprgb.c
+++ b/libgimpcolor/gimprgb.c
@@ -29,7 +29,7 @@
 
 
 /**
- * SECTION: GimpRGB
+ * SECTION: gimprgb
  * @title: GimpRGB
  * @short_description: Definitions and Functions relating to RGB colors.
  *
@@ -91,10 +91,10 @@ gimp_rgb_copy (const GimpRGB *rgb)
 
 /**
  * gimp_rgb_set:
- * @rgb: a #GimpRGB struct
- * @red:
- * @green:
- * @blue:
+ * @rgb:   a #GimpRGB struct
+ * @red:   the red component
+ * @green: the green component
+ * @blue:  the blue component
  *
  * Sets the red, green and blue components of @rgb and leaves the
  * alpha component unchanged. The color values should be between 0.0
@@ -116,8 +116,8 @@ gimp_rgb_set (GimpRGB *rgb,
 
 /**
  * gimp_rgb_set_alpha:
- * @rgb: a #GimpRGB struct
- * @alpha:
+ * @rgb:   a #GimpRGB struct
+ * @alpha: the alpha component
  *
  * Sets the alpha component of @rgb and leaves the RGB components unchanged.
  **/
@@ -132,10 +132,10 @@ gimp_rgb_set_alpha (GimpRGB *rgb,
 
 /**
  * gimp_rgb_set_uchar:
- * @rgb: a #GimpRGB struct
- * @red:
- * @green:
- * @blue:
+ * @rgb:   a #GimpRGB struct
+ * @red:   the red component
+ * @green: the green component
+ * @blue:  the blue component
  *
  * Sets the red, green and blue components of @rgb from 8bit values
  * (0 to 255) and leaves the alpha component unchanged.
@@ -266,7 +266,7 @@ gimp_rgb_gamma (GimpRGB *rgb,
 
 /**
  * gimp_rgb_luminance:
- * @rgb:
+ * @rgb: a #GimpRGB struct
  *
  * Return value: the luminous intensity of the range from 0.0 to 1.0.
  *
@@ -286,7 +286,7 @@ gimp_rgb_luminance (const GimpRGB *rgb)
 
 /**
  * gimp_rgb_luminance_uchar:
- * @rgb:
+ * @rgb: a #GimpRGB struct
  *
  * Return value: the luminous intensity in the range from 0 to 255.
  *
@@ -302,7 +302,7 @@ gimp_rgb_luminance_uchar (const GimpRGB *rgb)
 
 /**
  * gimp_rgb_intensity:
- * @rgb:
+ * @rgb: a #GimpRGB struct
  *
  * This function is deprecated! Use gimp_rgb_luminance() instead.
  *
@@ -322,7 +322,7 @@ gimp_rgb_intensity (const GimpRGB *rgb)
 
 /**
  * gimp_rgb_intensity_uchar:
- * @rgb:
+ * @rgb: a #GimpRGB struct
  *
  * This function is deprecated! Use gimp_rgb_luminance_uchar() instead.
  *
@@ -385,11 +385,11 @@ gimp_rgb_composite (GimpRGB              *color1,
 
 /**
  * gimp_rgba_set:
- * @rgba: a #GimpRGB struct
- * @red:
- * @green:
- * @blue:
- * @alpha:
+ * @rgba:  a #GimpRGB struct
+ * @red:   the red component
+ * @green: the green component
+ * @blue:  the blue component
+ * @alpha: the alpha component
  *
  * Sets the red, green, blue and alpha components of @rgb. The values
  * should be between 0.0 and 1.0 but there is no check to enforce this
@@ -412,11 +412,11 @@ gimp_rgba_set (GimpRGB *rgba,
 
 /**
  * gimp_rgba_set_uchar:
- * @rgba: a #GimpRGB struct
- * @red:
- * @green:
- * @blue:
- * @alpha:
+ * @rgba:  a #GimpRGB struct
+ * @red:   the red component
+ * @green: the green component
+ * @blue:  the blue component
+ * @alpha: the alpha component
  *
  * Sets the red, green, blue and alpha components of @rgb from 8bit
  * values (0 to 255).