cicp: Improve the docs

Fix some formatting issues, and document GdkCicpRange.

gdk/gdkcicpparams.c

@@ -159,14 +159,17 @@ gdk_cicp_params_class_init (GdkCicpParamsClass *klass)
   /**
    * GdkCicpParams:color-primaries:
    *
+   * The color primaries to use.
+   *
    * Supported values:
-   * 1 - BT.709 / sRGB
-   * 2 - unspecified
-   * 5 - PAL
-   * 6,7 - BT.601 / NTSC
-   * 9 - BT.2020
-   * 10 - CIE XYZ
-   * 12 - Display P3
+   *
+   * - 1: BT.709 / sRGB
+   * - 2: unspecified
+   * - 5: PAL
+   * - 6,7: BT.601 / NTSC
+   * - 9: BT.2020
+   * - 10: CIE XYZ
+   * - 12: Display P3
    *
    * Since: 4.16
    */
@@ -178,15 +181,18 @@ gdk_cicp_params_class_init (GdkCicpParamsClass *klass)
   /**
    * GdkCicpParams:transfer-function:
    *
+   * The transfer function to use.
+   *
    * Supported values:
-   * 1,6,14,15 - BT.709, BT.601, BT.2020
-   * 2 - unspecified
-   * 4 - gamma 2.2
-   * 5 - gamma 2.8
-   * 8 - linear
-   * 13 - sRGB
-   * 16 - BT.2100 PQ
-   * 18 - BT.2100 HLG
+   *
+   * - 1,6,14,15: BT.709, BT.601, BT.2020
+   * - 2: unspecified
+   * - 4: gamma 2.2
+   * - 5: gamma 2.8
+   * - 8: linear
+   * - 13: sRGB
+   * - 16: BT.2100 PQ
+   * - 18: BT.2100 HLG
    *
    * Since: 4.16
    */
@@ -198,9 +204,12 @@ gdk_cicp_params_class_init (GdkCicpParamsClass *klass)
   /**
    * GdkCicpParams:matrix-coefficients:
    *
+   * The matrix coefficients (for YUV to RGB conversion).
+   *
    * Supported values:
-   * 0 - RGB
-   * 2 - unspecified
+   *
+   * - 0: RGB
+   * - 2: unspecified
    *
    * Since: 4.16
    */
@@ -212,6 +221,8 @@ gdk_cicp_params_class_init (GdkCicpParamsClass *klass)
   /**
    * GdkCicpParams:range:
    *
+   * Whether the data is using the full range of values.
+   *
    * The range of the data.
    *
    * Since: 4.16

gdk/gdkcicpparams.h

@@ -55,6 +55,20 @@ GDK_AVAILABLE_IN_4_16
 void            gdk_cicp_params_set_matrix_coefficients (GdkCicpParams    *self,
                                                          guint             matrix_coefficients);
 
+/**
+ * GdkCicpRange:
+ * @GDK_CICP_RANGE_NARROW: The values use the range of 16-235 (for Y) and 16-240 for u and v.
+ * @GDK_CICO_RANGE_FULL: The values use the full range.
+ *
+ * The values of this enumeration describe whether image data uses
+ * the full range of 8-bit values.
+ *
+ * In digital broadcasting, it is common to reserve the lowest and
+ * highest values. Typically the allowed values for the narrow range
+ * are 16-235 for Y and 16-240 for u,v (when dealing with YUV data).
+ *
+ * Since: 4.16
+ */
 typedef enum
 {
   GDK_CICP_RANGE_NARROW,

gdk/gdkcolorstate.c

@@ -89,7 +89,7 @@ void
  * This color state uses the primaries defined by BT.709-6 and the transfer function
  * defined by IEC 61966-2-1.
  *
- * It is equivalent to H.273 ColourPrimaries 1 with TransferCharacteristics 13 and MatrixCoefficients 0.
+ * It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/13/0/1.
  *
  * See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB)
  * for details about this colorstate.
@@ -111,7 +111,7 @@ gdk_color_state_get_srgb (void)
  *
  * This color state uses the primaries defined by BT.709-6 and a linear transfer function.
  *
- * It is equivalent to H.273 ColourPrimaries 1 with TransferCharacteristics 8 and MatrixCoefficients 0.
+ * It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/8/0/1.
  *
  * See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB-linear)
  * for details about this colorstate.
@@ -134,7 +134,7 @@ gdk_color_state_get_srgb_linear (void)
  * This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and the transfer
  * function defined by SMPTE ST 2084 and BT.2100-2.
  *
- * It is equivalent to H.273 ColourPrimaries code point 9 with TransferCharacteristics 16.
+ * It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/16/0/1.
  *
  * See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-pq)
  * for details about this colorstate.
@@ -157,7 +157,7 @@ gdk_color_state_get_rec2100_pq (void)
  * This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and a linear
  * transfer function.
  *
- * It is equivalent to H.273 ColourPrimaries code point 9 with TransferCharacteristics 8.
+ * It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/8/0/1.
  *
  * See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-linear)
  * for details about this colorstate.