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

@@ -1,3 +1,13 @@
+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/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.
  */

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

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);

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)

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)

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)
 {