From: Stefan Kost Date: Fri, 18 Nov 2005 16:04:28 +0000 (+0000) Subject: gst/: docs fixes X-Git-Tag: RELEASE-0_9_6~91 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=dff771f1b7a1b4483e91d643d3cf17e5a5e04951;p=platform%2Fupstream%2Fgstreamer.git 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 --- diff --git a/ChangeLog b/ChangeLog index 00e0095..59ef62f 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,12 @@ +2005-11-18 Stefan Kost + + * gst/gstcaps.c: + * gst/gstghostpad.c: + * gst/gsttrace.c: + * gst/gstvalue.c: + * gst/gstvalue.h: + docs fixes + 2005-11-18 Andy Wingo * gst/net/gstnetclientclock.c: Turn off debugging. diff --git a/gst/gstcaps.c b/gst/gstcaps.c index fa5a06a..fa84549 100644 --- a/gst/gstcaps.c +++ b/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) diff --git a/gst/gstghostpad.c b/gst/gstghostpad.c index 075f2fe..aaa9185 100644 --- a/gst/gstghostpad.c +++ b/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" diff --git a/gst/gsttrace.c b/gst/gsttrace.c index ddaa46f..3e3deec 100644 --- a/gst/gsttrace.c +++ b/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 diff --git a/gst/gstvalue.c b/gst/gstvalue.c index 584d413..2fc0929 100644 --- a/gst/gstvalue.c +++ b/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, diff --git a/gst/gstvalue.h b/gst/gstvalue.h index ebbfaad..a9eaecb 100644 --- a/gst/gstvalue.h +++ b/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;