docs/gst/: rearrange gstvalue section

Original commit message from CVS:

* docs/gst/gstreamer-sections.txt:
* docs/gst/tmpl/gstvalue.sgml:
rearrange gstvalue section
* gst/gstutils.c: (gst_element_state_get_name):
NONE -> VOID
* gst/gstvalue.c: (_gst_value_initialize):
* gst/gstvalue.h:
doc updates

3 files changed, 115 insertions, 20 deletions

diff --git a/gst/gstutils.c b/gst/gstutils.c
index 447bf9a0e..a43efaa0f 100644
--- a/gst/gstutils.c
+++ b/gst/gstutils.c
@@ -715,7 +715,7 @@ gst_element_state_get_name (GstState state)
   switch (state) {
 #ifdef GST_DEBUG_COLOR
     case GST_STATE_VOID_PENDING:
-      return "NONE_PENDING";
+      return "VOID_PENDING";
       break;
     case GST_STATE_NULL:
       return "\033[01;34mNULL\033[00m";
@@ -734,7 +734,7 @@ gst_element_state_get_name (GstState state)
       return g_strdup_printf ("\033[01;35;41mUNKNOWN!\033[00m(%d)", state);
 #else
     case GST_STATE_VOID_PENDING:
-      return "NONE_PENDING";
+      return "VOID_PENDING";
       break;
     case GST_STATE_NULL:
       return "NULL";
diff --git a/gst/gstvalue.c b/gst/gstvalue.c
index 3c01829e6..43bf8e1a5 100644
--- a/gst/gstvalue.c
+++ b/gst/gstvalue.c
@@ -274,7 +274,7 @@ gst_value_list_append_value (GValue * value, const GValue * append_value)
 
 /**
  * gst_value_list_get_size:
- * @value: a GstValueList
+ * @value: a #GValue of type #GST_LIST_TYPE or #GST_ARRAY_TYPE
  *
  * Gets the number of values contained in @value.
  *
@@ -291,7 +291,7 @@ gst_value_list_get_size (const GValue * value)
 
 /**
  * gst_value_list_get_value:
- * @value: a GstValueList
+ * @value: a #GValue of type #GST_LIST_TYPE or #GST_ARRAY_TYPE
  * @index: index of value to get from the list
  *
  * Gets the value that is a member of the list contained in @value and
@@ -466,8 +466,8 @@ gst_value_lcopy_fourcc (const GValue * value, guint n_collect_values,
 
 /**
  * gst_value_set_fourcc:
- * @value: a GValue initialized to GST_TYPE_FOURCC
- * @fourcc: the fourcc to set
+ * @value: a GValue initialized to #GST_TYPE_FOURCC
+ * @fourcc: the #guint32 fourcc to set
  *
  * Sets @value to @fourcc.
  */
@@ -481,11 +481,11 @@ gst_value_set_fourcc (GValue * value, guint32 fourcc)
 
 /**
  * gst_value_get_fourcc:
- * @value: a GValue initialized to GST_TYPE_FOURCC
+ * @value: a GValue initialized to #GST_TYPE_FOURCC
  *
- * Gets the fourcc contained in @value.
+ * Gets the #guint32 fourcc contained in @value.
  *
- * Returns: the fourcc contained in @value.
+ * Returns: the #guint32 fourcc contained in @value.
  */
 guint32
 gst_value_get_fourcc (const GValue * value)
@@ -2685,7 +2685,7 @@ gst_value_lcopy_fraction (const GValue * value, guint n_collect_values,
 
 /**
  * gst_value_set_fraction:
- * @value: a GValue initialized to GST_TYPE_FRACTION
+ * @value: a GValue initialized to #GST_TYPE_FRACTION
  * @numerator: the numerator of the fraction
  * @denominator: the denominator of the fraction
  *
@@ -2721,7 +2721,7 @@ gst_value_set_fraction (GValue * value, gint numerator, gint denominator)
 
 /**
  * gst_value_get_fraction_numerator:
- * @value: a GValue initialized to GST_TYPE_FRACTION
+ * @value: a GValue initialized to #GST_TYPE_FRACTION
  *
  * Gets the numerator of the fraction specified by @value.
  *
@@ -2737,7 +2737,7 @@ gst_value_get_fraction_numerator (const GValue * value)
 
 /**
  * gst_value_get_fraction_denominator:
- * @value: a GValue initialized to GST_TYPE_FRACTION
+ * @value: a GValue initialized to #GST_TYPE_FRACTION
  *
  * Gets the denominator of the fraction specified by @value.
  *
@@ -2753,9 +2753,9 @@ gst_value_get_fraction_denominator (const GValue * value)
 
 /**
  * gst_value_fraction_multiply:
- * @product: a GValue initialized to GST_TYPE_FRACTION
- * @factor1: a GValue initialized to GST_TYPE_FRACTION
- * @factor2: a GValue initialized to GST_TYPE_FRACTION
+ * @product: a GValue initialized to #GST_TYPE_FRACTION
+ * @factor1: a GValue initialized to #GST_TYPE_FRACTION
+ * @factor2: a GValue initialized to #GST_TYPE_FRACTION
  *
  * Multiplies the two GValues containing a GstFraction and sets @product
  * to the product of the two fractions.
@@ -3142,11 +3142,6 @@ _gst_value_initialize (void)
       gst_value_deserialize_buffer,
     };
 
-#if 0
-    info.value_table = &value_table;
-    gst_type_fourcc =
-        g_type_register_static (G_TYPE_BOXED, "GstFourcc", &info, 0);
-#endif
     gst_value.type = GST_TYPE_BUFFER;
     gst_value_register (&gst_value);
   }
diff --git a/gst/gstvalue.h b/gst/gstvalue.h
index ccdb6d946..137b51a56 100644
--- a/gst/gstvalue.h
+++ b/gst/gstvalue.h
@@ -25,29 +25,129 @@
 
 G_BEGIN_DECLS
 
+/**
+ * GST_MAKE_FOURCC:
+ * @a: the first character
+ * @b: the second character
+ * @c: the third character
+ * @d: the fourth character
+ *
+ * Transform four characters into a #guint32 fourcc value with host
+ * endianness.
+ * <informalexample>
+ * <programlisting>
+ * guint32 fourcc = GST_MAKE_FOURCC ('M', 'J', 'P', 'G');
+ * </programlisting>
+ * </informalexample>
+ */
 #define GST_MAKE_FOURCC(a,b,c,d)        (guint32)((a)|(b)<<8|(c)<<16|(d)<<24)
+
+/**
+ * GST_STR_FOURCC:
+ * @f: a string with at least four characters
+ *
+ * Transform an input string into a #guint32 fourcc value with host
+ * endianness.
+ * Caller is responsible for ensuring the input string consists of at least
+ * four characters.
+ * <informalexample>
+ * <programlisting>
+ * guint32 fourcc = GST_STR_FOURCC ("MJPG");
+ * </programlisting>
+ * </informalexample>
+ */
 #define GST_STR_FOURCC(f)               (guint32)(((f)[0])|((f)[1]<<8)|((f)[2]<<16)|((f)[3]<<24))
 
+/**
+ * GST_FOURCC_FORMAT:
+ *
+ * Can be used together with #GST_FOURCC_ARGS to properly output a
+ * #guint32 fourcc value in a printf()-style text message.
+ * <informalexample>
+ * <programlisting>
+ * printf ("fourcc: %" GST_FOURCC_FORMAT "\n", GST_FOURCC_ARGS (fcc));
+ * </programlisting>
+ * </informalexample>
+ */
 #define GST_FOURCC_FORMAT "%c%c%c%c"
+
+/**
+ * GST_FOURCC_ARGS:
+ * @fourcc: a #guint32 fourcc value to output
+ *
+ * Can be used together with #GST_FOURCC_FORMAT to properly output a
+ * #guint32 fourcc value in a printf()-style text message.
+ */
 #define GST_FOURCC_ARGS(fourcc) \
         ((gchar) ((fourcc)     &0xff)), \
         ((gchar) (((fourcc)>>8 )&0xff)), \
         ((gchar) (((fourcc)>>16)&0xff)), \
         ((gchar) (((fourcc)>>24)&0xff))
 
+/**
+ * GST_VALUE_HOLDS_FOURCC:
+ *
+ * Checks if the given #GValue contains a #GST_TYPE_FOURCC value.
+ *
+ * @x: the #GValue to check
+ */
 #define GST_VALUE_HOLDS_FOURCC(x)       (G_VALUE_HOLDS(x, gst_type_fourcc))
+
+/**
+ * GST_VALUE_HOLDS_INT_RANGE:
+ *
+ * Checks if the given #GValue contains a #GST_TYPE_INT_RANGE value.
+ *
+ * @x: the #GValue to check
+ */
 #define GST_VALUE_HOLDS_INT_RANGE(x)    (G_VALUE_HOLDS(x, gst_type_int_range))
+
+/**
+ * GST_VALUE_HOLDS_DOUBLE_RANGE:
+ *
+ * Checks if the given #GValue contains a #GST_TYPE_DOUBLE_RANGE value.
+ *
+ * @x: the #GValue to check
+ */
 #define GST_VALUE_HOLDS_DOUBLE_RANGE(x) (G_VALUE_HOLDS(x, gst_type_double_range))
 #define GST_VALUE_HOLDS_LIST(x)		(G_VALUE_HOLDS(x, gst_type_list))
 #define GST_VALUE_HOLDS_ARRAY(x)	(G_VALUE_HOLDS(x, gst_type_array))
 #define GST_VALUE_HOLDS_CAPS(x)		(G_VALUE_HOLDS(x, GST_TYPE_CAPS))
+#define GST_VALUE_HOLDS_BUFFER(x)       (G_VALUE_HOLDS(x, GST_TYPE_BUFFER))
+
 #define GST_VALUE_HOLDS_FRACTION(x)	(G_VALUE_HOLDS(x, gst_type_fraction))
 
 #define GST_TYPE_FOURCC                  gst_type_fourcc
 #define GST_TYPE_INT_RANGE               gst_type_int_range
 #define GST_TYPE_DOUBLE_RANGE            gst_type_double_range
+/**
+ * GST_TYPE_LIST:
+ *
+ * a #GValue type that represents an unordered list of #GValue values
+ *
+ * Returns: the #GType of GstValueList (which is not explicitly typed)
+ */
+
 #define GST_TYPE_LIST                    gst_type_list
+
+/**
+ * GST_TYPE_ARRAY:
+ *
+ * a #GValue type that represents an ordered list of #GValue values
+ *
+ * Returns: the #GType of GstArrayList (which is not explicitly typed)
+ */
 #define GST_TYPE_ARRAY			 gst_type_array
+
+/**
+ * GST_TYPE_FRACTION:
+ *
+ * a #GValue type that represents a fraction of an integer numerator over
+ * an integer denominator
+ *
+ * Returns: the #GType of GstFraction (which is not explicitly typed)
+ */
+
 #define GST_TYPE_FRACTION                gst_type_fraction
 
 #define GST_VALUE_LESS_THAN              (-1)