From c3fecfa6f8b22cb971fe8ddd56dff33ca6fe1742 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Thu, 20 Oct 2005 21:08:47 +0000 Subject: [PATCH] gst/: More docs. Original commit message from CVS: * gst/gsterror.c: (gst_error_get_message): * gst/gstparse.h: * gst/gstquery.h: * gst/gststructure.c: * gst/gsttrace.c: * gst/gstutils.c: More docs. --- ChangeLog | 10 ++++++++++ gst/gsterror.c | 2 ++ gst/gstparse.h | 5 +++++ gst/gstquery.h | 35 +++++++++++++++++++++++++++++++---- gst/gststructure.c | 6 +++++- gst/gsttrace.c | 4 +++- gst/gstutils.c | 32 ++++++++++++++++++++++++++++++++ 7 files changed, 88 insertions(+), 6 deletions(-) diff --git a/ChangeLog b/ChangeLog index b872b505a7..dfe2b7a7f5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2005-10-20 Wim Taymans + + * gst/gsterror.c: (gst_error_get_message): + * gst/gstparse.h: + * gst/gstquery.h: + * gst/gststructure.c: + * gst/gsttrace.c: + * gst/gstutils.c: + More docs. + 2005-10-20 Wim Taymans * gst/gstbuffer.h: diff --git a/gst/gsterror.c b/gst/gsterror.c index 30640d2719..3b5d7f2f30 100644 --- a/gst/gsterror.c +++ b/gst/gsterror.c @@ -177,6 +177,8 @@ QUARK_FUNC (core) * @domain: the GStreamer error domain this error belongs to. * @code: the error code belonging to the domain. * + * Get a string describing the error message in the current locale. + * * Returns: a newly allocated string describing the error message in the * current locale. */ diff --git a/gst/gstparse.h b/gst/gstparse.h index 58127d6fda..e25929396d 100644 --- a/gst/gstparse.h +++ b/gst/gstparse.h @@ -30,6 +30,11 @@ G_BEGIN_DECLS #ifndef GST_DISABLE_PARSE GQuark gst_parse_error_quark (void); +/** + * GST_PARSE_ERROR: + * + * Get access to the error quark of the parse subsystem. + */ #define GST_PARSE_ERROR gst_parse_error_quark () typedef enum diff --git a/gst/gstquery.h b/gst/gstquery.h index 9f13d781cc..8a7ba50104 100644 --- a/gst/gstquery.h +++ b/gst/gstquery.h @@ -136,11 +136,38 @@ G_CONST_RETURN GstQueryTypeDefinition* GstIterator* gst_query_type_iterate_definitions (void); /* refcounting */ -#define gst_query_ref(msg) GST_QUERY (gst_mini_object_ref (GST_MINI_OBJECT (msg))) -#define gst_query_unref(msg) gst_mini_object_unref (GST_MINI_OBJECT (msg)) +/** + * gst_query_ref: + * @q: a #GstQuery to increase the refcount of. + * + * Increases the refcount of the given query by one. + */ +#define gst_query_ref(q) GST_QUERY (gst_mini_object_ref (GST_MINI_OBJECT (q))) +/** + * gst_query_unref: + * @q: a #GstQuery to decrease the refcount of. + * + * Decreases the refcount of the query. If the refcount reaches 0, the query + * will be freed. + */ +#define gst_query_unref(q) gst_mini_object_unref (GST_MINI_OBJECT (q)) + /* copy query */ -#define gst_query_copy(msg) GST_QUERY (gst_mini_object_copy (GST_MINI_OBJECT (msg))) -#define gst_query_make_writable(msg) GST_QUERY (gst_mini_object_make_writable (GST_MINI_OBJECT (msg))) +/** + * gst_query_copy: + * @q: a #GstQuery to copy. + * + * Copies the given query using the copy function of the parent #GstData + * structure. + */ +#define gst_query_copy(q) GST_QUERY (gst_mini_object_copy (GST_MINI_OBJECT (q))) +/** + * gst_query_make_writable: + * @q: a #GstQuery to make writable + * + * Makes a writable query from the given query. + */ +#define gst_query_make_writable(q) GST_QUERY (gst_mini_object_make_writable (GST_MINI_OBJECT (q))) /* position query */ GstQuery* gst_query_new_position (GstFormat format); diff --git a/gst/gststructure.c b/gst/gststructure.c index 46a4643eea..cce7c80375 100644 --- a/gst/gststructure.c +++ b/gst/gststructure.c @@ -293,6 +293,8 @@ gst_structure_get_name (const GstStructure * structure) * @structure: a #GstStructure * @name: structure name to check for * + * Checks if the structure has the given name + * * Returns: TRUE if @name matches the name of the structure. */ gboolean @@ -722,7 +724,9 @@ gst_structure_n_fields (const GstStructure * structure) * @structure: a #GstStructure * @index: the index to get the name of * - * Returns: the name of the given field number, counting from 0 onwards. + * Get the name of the given field number, counting from 0 onwards. + * + * Returns: the name of the given field number */ const gchar * gst_structure_nth_field_name (const GstStructure * structure, guint index) diff --git a/gst/gsttrace.c b/gst/gsttrace.c index 20d200ff0a..ddaa46f5b3 100644 --- a/gst/gsttrace.c +++ b/gst/gsttrace.c @@ -241,7 +241,9 @@ gst_alloc_trace_list (void) /** * gst_alloc_trace_live_all: * - * Returns the total number of live registered alloc trace objects. + * Get the total number of live registered alloc trace objects. + * + * Returns: the total number of live registered alloc trace objects. */ int gst_alloc_trace_live_all (void) diff --git a/gst/gstutils.c b/gst/gstutils.c index 13f3e1fe6e..5cc7ba0306 100644 --- a/gst/gstutils.c +++ b/gst/gstutils.c @@ -1899,6 +1899,26 @@ gst_object_default_error (GstObject * source, GError * error, gchar * debug) static GSystemThread zero_thread; +/** + * g_static_rec_cond_timed_wait: + * @cond: the GCond to wait for + * @mutex: a currently locked mutex + * @end_time: timeout value. + * + * Waits until this thread is woken up on cond, but not longer than until the + * time, that is specified by abs_time. The mutex is fully unlocked before falling + * asleep and fully locked again before resuming. + * + * If abs_time is NULL, g_static_rec_cond_timed_wait() acts like g_static_rec_cond_wait(). + * + * This function can also be used, if g_thread_init() has not yet been called and will + * immediately return TRUE then. + * + * To easily calculate abs_time a combination of g_get_current_time() and g_time_val_add() + * can be used. + * + * Returns: TRUE, if the thread is woken up in time. + */ gboolean g_static_rec_cond_timed_wait (GCond * cond, GStaticRecMutex * mutex, GTimeVal * end_time) @@ -1929,6 +1949,18 @@ g_static_rec_cond_timed_wait (GCond * cond, return res; } +/** + * g_static_rec_cond_wait: + * @cond: the GCond to wait for + * @mutex: a currently locked mutex + * + * Waits until this thread is woken up on cond. + * The mutex is fully unlocked before falling + * asleep and fully locked again before resuming. + * + * This function can also be used, if g_thread_init() has not yet been called and will + * immediately return then. + */ void g_static_rec_cond_wait (GCond * cond, GStaticRecMutex * mutex) {