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.

diff --git a/ChangeLog b/ChangeLog
index b872b50..dfe2b7a 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,15 @@
 2005-10-20  Wim Taymans  <wim@fluendo.com>
 
+       * 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  <wim@fluendo.com>
+
        * gst/gstbuffer.h:
        * gst/gstpad.c:
        * gst/gstparse.c:

diff --git a/gst/gsterror.c b/gst/gsterror.c
index 30640d2..3b5d7f2 100644 (file)
--- 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 58127d6..e259293 100644 (file)
--- 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 9f13d78..8a7ba50 100644 (file)
--- 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 46a4643..cce7c80 100644 (file)
--- 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 20d200f..ddaa46f 100644 (file)
--- 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 13f3e1f..5cc7ba0 100644 (file)
--- 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)
 {