gst/: docs fixes

Original commit message from CVS:
* gst/gstcaps.c:
* gst/gstghostpad.c:
* gst/gsttrace.c:
* gst/gstvalue.c:
* gst/gstvalue.h:
docs fixes

ChangeLog

@@ -1,3 +1,12 @@
+2005-11-18  Stefan Kost  <ensonic@users.sf.net>
+
+	* gst/gstcaps.c:
+	* gst/gstghostpad.c:
+	* gst/gsttrace.c:
+	* gst/gstvalue.c:
+	* gst/gstvalue.h:
+	  docs fixes
+
 2005-11-18  Andy Wingo  <wingo@pobox.com>
 
 	* gst/net/gstnetclientclock.c: Turn off debugging.

gst/gstcaps.c

@@ -22,7 +22,7 @@
  * @short_description: Structure describing sets of media formats
  * @see_also: #GstStructure
  *
- * Caps are lighweight refcounted objects describing media types.
+ * Caps (capabilities) are lighweight refcounted objects describing media types.
  * They are composed of an array of #GstStructure.
  *
  * Caps are exposed on #GstPadTemplate to describe all possible types a
@@ -31,7 +31,7 @@
  *
  * Caps are exposed on the element pads using the gst_pad_get_caps() pad 
  * function. This function describes the possible types that the pad can 
- * handle or produce at runtime. 
+ * handle or produce at runtime.
  *
  * Caps are also attached to buffers to describe to content of the data
  * pointed to by the buffer with gst_buffer_set_caps(). Caps attached to
@@ -57,7 +57,7 @@
  * gst_caps_is_fixed() to test for fixed caps. Only fixed caps can be
  * set on a #GstPad or #GstBuffer.
  *
- * Various methods exist to work with the media types such as substracting
+ * Various methods exist to work with the media types such as subtracting
  * or intersecting.
  *
  * Last reviewed on 2005-11-09 (0.9.4)

gst/gstghostpad.c

@@ -26,6 +26,19 @@
  * @short_description: Pseudo link pads
  * @see_also: #GstPad
  *
+ * GhostPads are useful when organizing pipelines with #GstBin like elements.
+ * The idea here is to create hierarchical element graphs. The bin element
+ * contains a sub-graph. Now one would like to treat the bin-element like other
+ * #GstElements. This is where GhostPads come into play. A GhostPad acts as a
+ * proxy for another pad. Thus the bin can have sink and source ghost-pads that
+ * are accociated with sink and source pads of the child elements.
+ *
+ * If the target pad is known at creation time, gst_ghost_pad_new() is the
+ * function to use to get a ghost-pad. Otherwise one can use gst_ghost_pad_new_notarget()
+ * to create the ghost-pad and use gst_ghost_pad_set_target() to establish the
+ * accociation later on.
+ *
+ * Last reviewed on 2005-11-18 (0.9.5)
  */
 
 #include "gst_private.h"

gst/gsttrace.c

@@ -24,6 +24,13 @@
  * SECTION:gsttrace
  * @short_description: Tracing functionality
  *
+ * Traces allows to track object allocation. They provide a instance counter per
+ * #GType. The counter is incremented for each object allocated and decremented
+ * it when it's freed.
+ *
+ * (FIXME: add example - see jamboree/tests/read-tags.c)
+ *
+ * Last reviewed on 2005-11-18 (0.9.5)
  */
 
 #ifdef HAVE_CONFIG_H

gst/gstvalue.c

@@ -2177,8 +2177,9 @@ gst_value_can_union (const GValue * value1, const GValue * value2)
  *
  * Creates a GValue cooresponding to the union of @value1 and @value2.
  *
- * Returns: TRUE if the values could be unioned
+ * Returns: %TRUE if a union was successful
  */
+/* FIXME: change return type to 'void'? */
 gboolean
 gst_value_union (GValue * dest, const GValue * value1, const GValue * value2)
 {
@@ -2363,7 +2364,7 @@ gst_value_register_intersect_func (GType type1, GType type2,
  * Subtracts @subtrahend from @minuend and stores the result in @dest.
  * Note that this means subtraction as in sets, not as in mathematics.
  *
- * Returns: TRUE if the subtraction is not empty
+ * Returns: %TRUE if the subtraction is not empty
  */
 gboolean
 gst_value_subtract (GValue * dest, const GValue * minuend,

gst/gstvalue.h

@@ -267,24 +267,86 @@ G_BEGIN_DECLS
 typedef int      (* GstValueCompareFunc)     (const GValue *value1,
 					      const GValue *value2);
 
+/**
+ * GstValueSerializeFunc:
+ * @value1: a #GValue
+ *
+ * Used by gst_value_serialize() to obtain a non-binary form of the #GValue.
+ *
+ * Returns: the string representation of the value
+ */
 typedef char *   (* GstValueSerializeFunc)   (const GValue *value1);
 
+/**
+ * GstValueDeserializeFunc:
+ * @dest: a #GValue
+ * @s: a string
+ *
+ * Used by gst_value_deserialize() to parse a non-binary form into the #GValue.
+ *
+ * Returns: %TRUE for success
+ */
 typedef gboolean (* GstValueDeserializeFunc) (GValue       *dest,
 					      const char   *s);
 
+/**
+ * GstValueUnionFunc:
+ * @dest: a #GValue for the result
+ * @value1: a #GValue operand
+ * @value2: a #GValue operand
+ *
+ * Used by gst_value_union() to perform unification for a specific #GValue
+ * type. Register a new implementation with gst_value_register_union_func().
+ *
+ * Returns: %TRUE if a union was successful
+ */
+/* FIXME: shouldn't the return value be gboolean ? */
 typedef int      (* GstValueUnionFunc)       (GValue       *dest,
 					      const GValue *value1,
 					      const GValue *value2);
 
+/**
+ * GstValueIntersectFunc:
+ * @dest: a #GValue for the result
+ * @value1: a #GValue operand
+ * @value2: a #GValue operand
+ *
+ * Used by gst_value_intersect() to perform intersection for a specific #GValue
+ * type. Register a new implementation with gst_value_register_intersection_func().
+ *
+ * Returns: %TRUE if the values can intersect
+ */
+/* FIXME: shouldn't the return value be gboolean ? */
 typedef int      (* GstValueIntersectFunc)   (GValue       *dest,
 					      const GValue *value1,
 					      const GValue *value2);
 
+/**
+ * GstValueSubtractFunc:
+ * @dest: a #GValue for the result
+ * @minuend: a #GValue operand
+ * @subtrahend: a #GValue operand
+ *
+ * Used by gst_value_subtract() to perform subtraction for a specific #GValue
+ * type. Register a new implementation with gst_value_register_subtract_func().
+ *
+ * Returns: %TRUE if the subtraction is not empty
+ */
+/* FIXME: shouldn't the return value be gboolean ? */
 typedef int      (* GstValueSubtractFunc)    (GValue       *dest,
 					      const GValue *minuend,
 					      const GValue *subtrahend);
 
 typedef struct _GstValueTable GstValueTable;
+/**
+ * GstValueTable:
+ * @type: a #GType
+ * @compare: a #GstValueCompareFunc
+ * @serialize: a #GstValueSerializeFunc
+ * @deserialize: a #GstValueDeserializeFunc
+ *
+ * VTable for the #GValue @type.
+ */
 struct _GstValueTable {
   GType type;
   GstValueCompareFunc compare;