Documentation updates

Original commit message from CVS:
Documentation updates
Added dump to identity
Fix some warnings in gstelement

gst/cothreads.c

@@ -374,12 +374,11 @@ cothread_getcurrent (void)
 }
 
 /**
- * cothread_set_data:
+ * cothread_set_private:
  * @thread: the cothread state
- * @key: a key for the data
  * @data: the data
  *
- * adds data to a cothread
+ * set private data for the cothread.
  */
 void
 cothread_set_private (cothread_state *thread, gpointer data)
@@ -387,6 +386,14 @@ cothread_set_private (cothread_state *thread, gpointer data)
   thread->priv = data;
 }
 
+/**
+ * cothread_context_set_data:
+ * @thread: the cothread state
+ * @key: a key for the data
+ * @data: the data
+ *
+ * adds data to a cothread
+ */
 void
 cothread_context_set_data (cothread_state *thread, gchar *key, gpointer data)
 {
@@ -396,13 +403,12 @@ cothread_context_set_data (cothread_state *thread, gchar *key, gpointer data)
 }
 
 /**
- * cothread_get_data:
+ * cothread_get_private:
  * @thread: the cothread state
- * @key: a key for the data
  *
- * get data from the cothread
+ * get the private data from the cothread
  *
- * Returns: the data assiciated with the key
+ * Returns: the private data of the cothread
  */
 gpointer
 cothread_get_private (cothread_state *thread)
@@ -410,6 +416,15 @@ cothread_get_private (cothread_state *thread)
   return thread->priv;
 }
 
+/**
+ * cothread_context_get_data:
+ * @thread: the cothread state
+ * @key: a key for the data
+ *
+ * get data from the cothread
+ *
+ * Returns: the data associated with the key
+ */
 gpointer
 cothread_context_get_data (cothread_state * thread, gchar * key)
 {

gst/elements/gstfakesink.c

@@ -266,8 +266,7 @@ gst_fakesink_chain (GstPad *pad, GstBuffer *buf)
 
   g_signal_emit (G_OBJECT (fakesink), gst_fakesink_signals[SIGNAL_HANDOFF], 0, buf, pad);
 
-  if (fakesink->dump)
+  if (fakesink->dump) {
-  {
     gst_util_dump_mem (GST_BUFFER_DATA (buf), GST_BUFFER_SIZE (buf));
   }
 

gst/elements/gstidentity.c

@@ -51,6 +51,7 @@ enum {
   ARG_DROP_PROBABILITY,
   ARG_SILENT,
   ARG_LAST_MESSAGE,
+  ARG_DUMP,
 };
 
 
@@ -116,6 +117,9 @@ gst_identity_class_init (GstIdentityClass *klass)
   g_object_class_install_property (G_OBJECT_CLASS (klass), ARG_LAST_MESSAGE,
     g_param_spec_string ("last-message", "last-message", "last-message",
                          NULL, G_PARAM_READABLE)); 
+  g_object_class_install_property (G_OBJECT_CLASS (klass), ARG_DUMP,
+    g_param_spec_boolean("dump","Dump","Dump buffer contents",
+                         FALSE, G_PARAM_READWRITE));
 
   gst_identity_signals[SIGNAL_HANDOFF] =
     g_signal_new ("handoff", G_TYPE_FROM_CLASS(klass), G_SIGNAL_RUN_LAST,
@@ -174,6 +178,7 @@ gst_identity_init (GstIdentity *identity)
   identity->error_after = -1;
   identity->drop_probability = 0.0;
   identity->silent = FALSE;
+  identity->dump = FALSE;
 }
 
 static void 
@@ -206,6 +211,9 @@ gst_identity_chain (GstPad *pad, GstBuffer *buf)
       return;
     }
   }
+  if (identity->dump) {
+    gst_util_dump_mem (GST_BUFFER_DATA (buf), GST_BUFFER_SIZE (buf));
+  }
 
   for (i = identity->duplicate; i; i--) {
     if (!identity->silent)
@@ -275,6 +283,9 @@ gst_identity_set_property (GObject *object, guint prop_id, const GValue *value,
     case ARG_DUPLICATE:
       identity->duplicate = g_value_get_uint (value);
       break;
+    case ARG_DUMP:
+      identity->dump = g_value_get_boolean (value);
+      break;
     case ARG_ERROR_AFTER:
       identity->error_after = g_value_get_uint (value);
       break;
@@ -313,6 +324,9 @@ static void gst_identity_get_property(GObject *object, guint prop_id, GValue *va
     case ARG_SILENT:
       g_value_set_boolean (value, identity->silent);
       break;
+    case ARG_DUMP:
+      g_value_set_boolean (value, identity->dump);
+      break;
     case ARG_LAST_MESSAGE:
       g_value_set_string (value, identity->last_message);
       break;

gst/elements/gstidentity.h

@@ -63,6 +63,7 @@ struct _GstIdentity {
   gfloat drop_probability;
   guint sleep_time;
   gboolean silent;
+  gboolean dump;
   gchar *last_message;
 };
 

gst/gstbin.c

@@ -26,7 +26,6 @@
 #include "gstevent.h"
 #include "gstbin.h"
 #include "gstxml.h"
-#include "gstsystemclock.h"
 
 #include "gstscheduler.h"
 
@@ -152,6 +151,14 @@ gst_bin_new (const gchar * name)
   return gst_elementfactory_make ("bin", name);
 }
 
+/**
+ * gst_bin_get_clock:
+ * @bin: the bin to get the clock of
+ *
+ * Get the current clock of the bin
+ *
+ * Returns: the clock of the bin
+ */
 GstClock*
 gst_bin_get_clock (GstBin *bin)
 {
@@ -164,6 +171,14 @@ gst_bin_get_clock (GstBin *bin)
   return NULL;
 }
 
+/**
+ * gst_bin_use_clock:
+ * @bin: the bin to set the clock for
+ * @clock: the clock to use.
+ *
+ * Force the bin to use the given clock. Use NULL to 
+ * force it to use no clock at all.
+ */
 void
 gst_bin_use_clock (GstBin *bin, GstClock *clock)
 {
@@ -174,6 +189,12 @@ gst_bin_use_clock (GstBin *bin, GstClock *clock)
     gst_scheduler_use_clock (GST_ELEMENT_SCHED (bin), clock);
 }
 
+/**
+ * gst_bin_auto_clock:
+ * @bin: the bin to autoclock
+ *
+ * Let the bin select a clock automatically.
+ */
 void
 gst_bin_auto_clock (GstBin *bin)
 {
@@ -273,14 +294,13 @@ gst_bin_unset_element_sched (GstElement *element, GstScheduler *sched)
 
 
 /**
- * gst_element_connect_elements_many:
+ * gst_bin_add_many:
+ * @bin: the bin to add the elements to
  * @element_1: the first element to add to the bin
  * @...: NULL-terminated list of elements to add to the bin
  * 
  * Add a list of elements to a bin. Uses #gst_bin_add.
- **/
+ */
-/* API FIXME: this should be called gst_element_connect_many, and connect_elements
- * should just be connect */
 void
 gst_bin_add_many (GstBin *bin, GstElement *element_1, ...)
 {

gst/gstcaps.c

@@ -697,6 +697,17 @@ gst_caps_intersect (GstCaps *caps1, GstCaps *caps2)
   return result;
 }
 
+/**
+ * gst_caps_normalize:
+ * @caps: a capabilty
+ *
+ * Make the normalisation of the caps. This will return a new caps
+ * that is equivalent to the input caps with the exception that all
+ * lists are unrolled. This function is useful when you want to iterate
+ * the caps.
+ *
+ * Returns: The normalisation of the caps.
+ */
 GstCaps*
 gst_caps_normalize (GstCaps *caps)
 {

gst/gstclock.c

@@ -138,6 +138,9 @@ gst_clock_class_init (GstClockClass *klass)
 
   parent_class = g_type_class_ref (GST_TYPE_OBJECT);
 
+  if (!g_thread_supported ())
+    g_thread_init (NULL);
+
   _gst_clock_entries_chunk = g_mem_chunk_new ("GstClockEntries",
                      sizeof (GstClockEntry), sizeof (GstClockEntry) * 32,
                      G_ALLOC_AND_FREE);
@@ -159,6 +162,14 @@ gst_clock_init (GstClock *clock)
   clock->active_cond = g_cond_new ();
 }
 
+/**
+ * gst_clock_async_supported
+ * @clock: The clock to query
+ *
+ * Check if this clock can support async notification.
+ *
+ * Returns: TRUE if async notification is supported.
+ */
 gboolean
 gst_clock_async_supported (GstClock *clock)
 {
@@ -167,7 +178,45 @@ gst_clock_async_supported (GstClock *clock)
   return clock->async_supported;
 }
 
+/**
+ * gst_clock_set_speed
+ * @clock: The clock to modify
+ * @speed: The speed to set on the clock
+ *
+ * Set the speed on the given clock. 1.0 is the default 
+ * speed.
+ */
+void
+gst_clock_set_speed (GstClock *clock, gdouble speed)
+{
+  g_return_if_fail (GST_IS_CLOCK (clock));
 
+  clock->speed = speed;
+}
+
+/**
+ * gst_clock_get_speed
+ * @clock: The clock to query
+ *
+ * Get the speed of the given clock.
+ *
+ * Returns: the speed of the clock.
+ */
+gdouble
+gst_clock_get_speed (GstClock *clock)
+{
+  g_return_val_if_fail (GST_IS_CLOCK (clock), 0.0);
+
+  return clock->speed;
+}
+
+
+/**
+ * gst_clock_reset
+ * @clock: The clock to reset
+ *
+ * Reset the clock to time 0.
+ */
 void
 gst_clock_reset (GstClock *clock)
 {
@@ -186,6 +235,14 @@ gst_clock_reset (GstClock *clock)
   GST_UNLOCK (clock);
 }
 
+/**
+ * gst_clock_activate
+ * @clock: The clock to activate
+ * @active: flag indication activate or deactivate
+ *
+ * Activates or deactivates the clock based on the activate paramater.
+ * As soon as the clock is activated, the time will start ticking.
+ */
 void
 gst_clock_activate (GstClock *clock, gboolean active)
 {
@@ -213,6 +270,14 @@ gst_clock_activate (GstClock *clock, gboolean active)
   g_mutex_unlock (clock->active_mutex);	
 }
 
+/**
+ * gst_clock_is_active
+ * @clock: The clock to query
+ *
+ * Checks if the given clock is active.
+ * 
+ * Returns: TRUE if the clock is active.
+ */
 gboolean
 gst_clock_is_active (GstClock *clock)
 {
@@ -221,6 +286,15 @@ gst_clock_is_active (GstClock *clock)
   return clock->active;
 }
 
+/**
+ * gst_clock_get_time
+ * @clock: The clock to query
+ *
+ * Get the current time of the given clock. The time is always
+ * monotonically increasing.
+ * 
+ * Returns: the time of the clock.
+ */
 GstClockTime
 gst_clock_get_time (GstClock *clock)
 {
@@ -270,6 +344,15 @@ gst_clock_wait_async_func (GstClock *clock, GstClockTime time,
   return entry;
 }
 
+/**
+ * gst_clock_wait
+ * @clock: The clock to wait on
+ * @time: The time to wait for
+ *
+ * Wait and block till the clock reaches the specified time.
+ *
+ * Returns: result of the operation.
+ */
 GstClockReturn
 gst_clock_wait (GstClock *clock, GstClockTime time)
 {
@@ -284,6 +367,19 @@ gst_clock_wait (GstClock *clock, GstClockTime time)
   return res;
 }
 
+/**
+ * gst_clock_wait_async
+ * @clock: The clock to wait on
+ * @time: The time to wait for
+ * @func: The callback function 
+ * @user_data: User data passed in the calback
+ *
+ * Register a callback on the given clock that will be triggered 
+ * when the clock has reached the given time. A ClockID is returned
+ * that can be used to cancel the request.
+ *
+ * Returns: the clock id or NULL when async notification is not supported.
+ */
 GstClockID
 gst_clock_wait_async (GstClock *clock, GstClockTime time,
 		      GstClockCallback func, gpointer user_data)
@@ -296,6 +392,52 @@ gst_clock_wait_async (GstClock *clock, GstClockTime time,
   return NULL;
 }
 
+/**
+ * gst_clock_cancel_wait_async
+ * @clock: The clock to cancel the request on
+ * @id: The id to cancel
+ *
+ * Cancel an outstanding async notification request with the given ID.
+ */
+void
+gst_clock_cancel_wait_async (GstClock *clock, GstClockID id)
+{
+  g_warning ("not supported");
+}
+
+/**
+ * gst_clock_notify_async
+ * @clock: The clock to wait on
+ * @interval: The interval between notifications
+ * @func: The callback function 
+ * @user_data: User data passed in the calback
+ *
+ * Register a callback on the given clock that will be periodically
+ * triggered with the specified interval. A ClockID is returned
+ * that can be used to cancel the request.
+ *
+ * Returns: the clock id or NULL when async notification is not supported.
+ */
+GstClockID
+gst_clock_notify_async (GstClock *clock, GstClockTime interval,
+		        GstClockCallback func, gpointer user_data) 
+{
+  g_warning ("not supported");
+}
+
+/**
+ * gst_clock_remove_notify_async
+ * @clock: The clock to cancel the request on
+ * @id: The id to cancel
+ *
+ * Cancel an outstanding async notification request with the given ID.
+ */
+void
+gst_clock_remove_notify_async (GstClock *clock, GstClockID id)
+{
+  g_warning ("not supported");
+}
+
 static void
 gst_clock_unlock_func (GstClock *clock, GstClockTime time, GstClockID id, gpointer user_data)
 {
@@ -306,6 +448,15 @@ gst_clock_unlock_func (GstClock *clock, GstClockTime time, GstClockID id, gpoint
   GST_CLOCK_ENTRY_UNLOCK (entry);
 }
 
+/**
+ * gst_clock_wait_id
+ * @clock: The clock to wait on
+ * @id: The clock id to wait on
+ *
+ * Wait and block on the clockid obtained with gst_clock_wait_async.
+ *
+ * Returns: result of the operation.
+ */
 GstClockReturn
 gst_clock_wait_id (GstClock *clock, GstClockID id)
 {
@@ -341,6 +492,14 @@ gst_clock_wait_id (GstClock *clock, GstClockID id)
   return res;
 }
 
+/**
+ * gst_clock_get_next_id
+ * @clock: The clock to query
+ *
+ * Get the clockid of the next event.
+ *
+ * Returns: a clockid or NULL is no event is pending.
+ */
 GstClockID
 gst_clock_get_next_id (GstClock *clock)
 {
@@ -354,6 +513,14 @@ gst_clock_get_next_id (GstClock *clock)
   return (GstClockID *) entry;
 }
 
+/**
+ * gst_clock_id_get_time
+ * @id: The clockid to query
+ *
+ * Get the time of the clock ID
+ *
+ * Returns: the time of the given clock id
+ */
 GstClockTime
 gst_clock_id_get_time (GstClockID id)
 {
@@ -372,6 +539,13 @@ gst_clock_free_entry (GstClock *clock, GstClockEntry *entry)
   g_mutex_unlock (_gst_clock_entries_chunk_lock);
 }
 
+/**
+ * gst_clock_unlock_id
+ * @clock: The clock that own the id
+ * @id: The clockid to unlock
+ *
+ * Unlock the ClockID.
+ */
 void
 gst_clock_unlock_id (GstClock *clock, GstClockID id)
 {
@@ -383,6 +557,13 @@ gst_clock_unlock_id (GstClock *clock, GstClockID id)
   gst_clock_free_entry (clock, entry);
 }
 
+/**
+ * gst_clock_set_resolution
+ * @clock: The clock set the resolution on
+ * @resolution: The resolution to set
+ *
+ * Set the accuracy of the clock.
+ */
 void
 gst_clock_set_resolution (GstClock *clock, guint64 resolution)
 {
@@ -392,6 +573,14 @@ gst_clock_set_resolution (GstClock *clock, guint64 resolution)
     CLASS (clock)->set_resolution (clock, resolution);
 }
 
+/**
+ * gst_clock_get_resolution
+ * @clock: The clock get the resolution of
+ *
+ * Get the accuracy of the clock.
+ *
+ * Returns: the resolution of the clock in microseconds.
+ */
 guint64
 gst_clock_get_resolution (GstClock *clock)
 {

gst/gstclock.h

@@ -90,7 +90,7 @@ struct _GstClockClass {
 GType           	gst_clock_get_type 		(void);
 
 void 			gst_clock_set_speed		(GstClock *clock, gdouble speed);
-void 			gst_clock_get_speed		(GstClock *clock, gdouble speed);
+gdouble 		gst_clock_get_speed		(GstClock *clock);
 
 void 			gst_clock_activate		(GstClock *clock, gboolean active);
 gboolean 		gst_clock_is_active		(GstClock *clock);

gst/gstelement.c

@@ -288,6 +288,8 @@ gst_element_set_clock (GstElement *element, GstClock *clock)
  * @element: GstElement to get the clock of
  *
  * Get the clock of the element
+ *
+ * Returns: the clock of the element.
  */
 GstClock*
 gst_element_get_clock (GstElement *element)
@@ -308,6 +310,8 @@ gst_element_get_clock (GstElement *element)
  * @time: the time to wait for
  *
  * Wait for a specific time on the clock
+ *
+ * Returns: the result of the wait operation
  */
 GstClockReturn
 gst_element_clock_wait (GstElement *element, GstClock *clock, GstClockTime time)
@@ -717,7 +721,8 @@ gst_element_request_pad_by_name (GstElement *element, const gchar *name)
   gboolean templ_found = FALSE;
   GList *list;
   gint n;
-  gchar *str, *data, *endptr;
+  const gchar *data;
+  gchar *str, *endptr;
 
   g_return_val_if_fail (element != NULL, NULL);
   g_return_val_if_fail (GST_IS_ELEMENT (element), NULL);
@@ -867,7 +872,7 @@ gst_element_get_compatible_pad (GstElement *element, GstPad *pad)
  + It will use request pads if possible. But both pads will not be requested.
  * If multiple connections are possible, only one is established.
  *
- * Return: TRUE if the elements could be connected.
+ * Returns: TRUE if the elements could be connected.
  */
 gboolean
 gst_element_connect_elements_filtered (GstElement *src, GstElement *dest, 
@@ -960,7 +965,7 @@ gst_element_connect_elements_filtered (GstElement *src, GstElement *dest,
  * Chain together a series of elements. Uses #gst_element_connect_elements.
  *
  * Returns: TRUE on success, FALSE otherwise.
- **/
+ */
 /* API FIXME: this should be called gst_element_connect_many, and connect_elements
  * should just be connect */
 gboolean
@@ -998,7 +1003,7 @@ gst_element_connect_elements_many (GstElement *element_1, GstElement *element_2,
  * connected yet. If multiple connections are possible, only one is
  * established.
  *
- * Return: TRUE if the elements could be connected.
+ * Returns: TRUE if the elements could be connected.
  */
 gboolean
 gst_element_connect_elements (GstElement *src, GstElement *dest)
@@ -1019,7 +1024,7 @@ gst_element_connect_elements (GstElement *src, GstElement *dest)
  * child of the parent of the other element.  If they have different
  * parents, the connection fails.
  *
- * Return: TRUE if the pads could be connected.
+ * Returns: TRUE if the pads could be connected.
  */
 gboolean
 gst_element_connect_filtered (GstElement *src, const gchar *srcpadname,
@@ -1063,7 +1068,7 @@ gst_element_connect_filtered (GstElement *src, const gchar *srcpadname,
  * child of the parent of the other element.  If they have different
  * parents, the connection fails.
  *
- * Return: TRUE if the pads could be connected.
+ * Returns: TRUE if the pads could be connected.
  */
 gboolean
 gst_element_connect (GstElement *src, const gchar *srcpadname,

gst/gstobject.h

@@ -146,7 +146,7 @@ gboolean	gst_object_check_uniqueness	(GList *list, const gchar *name);
 
 #ifndef GST_DISABLE_LOADSAVE_REGISTRY
 xmlNodePtr	gst_object_save_thyself		(GstObject *object, xmlNodePtr parent);
-void		gst_object_restore_thyself	(GstObject *object, xmlNodePtr parent);
+void		gst_object_restore_thyself	(GstObject *object, xmlNodePtr self);
 #else
 #pragma GCC poison gst_object_save_thyself
 #pragma GCC poison gst_object_restore_thyself

gst/gstpad.c

@@ -1261,8 +1261,9 @@ gst_pad_perform_negotiate (GstPad *srcpad, GstPad *sinkpad)
 
 /**
  * gst_pad_try_reconnect_filtered:
- * @pad: the pad to reconnect
+ * @srcpad: the source"pad to reconnect
- * @caps: the capabilities to use in the reconnectiong
+ * @sinkpad: the sink pad to reconnect
+ * @filtercaps: the capabilities to use in the reconnectiong
  *
  * Try to reconnect this pad and its peer with the specified caps
  *
@@ -1287,8 +1288,9 @@ gst_pad_try_reconnect_filtered (GstPad *srcpad, GstPad *sinkpad, GstCaps *filter
 
 /**
  * gst_pad_reconnect_filtered:
- * @pad: the pad to reconnect
+ * @srcpad: the source"pad to reconnect
- * @caps: the capabilities to use in the reconnectiong
+ * @sinkpad: the sink pad to reconnect
+ * @filtercaps: the capabilities to use in the reconnectiong
  *
  * Try to reconnect this pad and its peer with the specified caps. 
  *
@@ -1499,11 +1501,12 @@ gst_pad_get_allowed_caps (GstPad *pad)
 }
 
 /**
- * gst_pad_recac_allowed_caps:
+ * gst_pad_recalc_allowed_caps:
  * @pad: the pad to recaculate the caps of
  *
- * Attempt to reconnect the pad to its peer through its filter, set with gst_pad_[re]connect_filtered.
+ * Attempt to reconnect the pad to its peer through its filter, 
- * FIXME: no one calls this function. why is it here?
+ * set with gst_pad_[re]connect_filtered. This function is useful when a
+ * plugin has new capabilities on a pad and wants to notify the peer.
  *
  * Returns: TRUE on success, FALSE otherwise.
  */
@@ -2257,21 +2260,22 @@ static GstPad *ghost_pad_parent_class = NULL;
 /* static guint gst_ghost_pad_signals[LAST_SIGNAL] = { 0 }; */
 
 GType
-gst_ghost_pad_get_type(void) {
+gst_ghost_pad_get_type (void) 
+{
   if (!_gst_ghost_pad_type) {
     static const GTypeInfo pad_info = {
-      sizeof(GstGhostPadClass),
+      sizeof (GstGhostPadClass),
       NULL,
       NULL,
-      (GClassInitFunc)gst_ghost_pad_class_init,
+      (GClassInitFunc) gst_ghost_pad_class_init,
       NULL,
       NULL,
       sizeof(GstGhostPad),
       8,
-      (GInstanceInitFunc)gst_ghost_pad_init,
+      (GInstanceInitFunc) gst_ghost_pad_init,
       NULL
     };
-    _gst_ghost_pad_type = g_type_register_static(GST_TYPE_PAD, "GstGhostPad", &pad_info, 0);
+    _gst_ghost_pad_type = g_type_register_static (GST_TYPE_PAD, "GstGhostPad", &pad_info, 0);
   }
   return _gst_ghost_pad_type;
 }
@@ -2281,9 +2285,9 @@ gst_ghost_pad_class_init (GstGhostPadClass *klass)
 {
   GObjectClass *gobject_class;
 
-  gobject_class = (GObjectClass*)klass;
+  gobject_class = (GObjectClass*) klass;
 
-  ghost_pad_parent_class = g_type_class_ref(GST_TYPE_PAD);
+  ghost_pad_parent_class = g_type_class_ref (GST_TYPE_PAD);
 }
 
 static void

gst/gstprops.c

@@ -327,6 +327,12 @@ gst_props_new (const gchar *firstname, ...)
 } 
 
 
+/**
+ * gst_props_debug:
+ * @props: the props to debug
+ *
+ * Dump the contents of the given properties into the DEBUG log.
+ */
 void
 gst_props_debug (GstProps *props)
 {
@@ -583,7 +589,7 @@ gst_props_newv (const gchar *firstname, va_list var_args)
  * For the optional args, use GST_PROPS_FOO, where FOO is INT,
  * STRING, etc. This macro expands to a variable number of arguments,
  * hence the lack of precision in the function prototype. No
- * terminating NULL is necessary.
+ * terminating NULL is necessary as only one property can be changed.
  *
  * Returns: the new modified property structure.
  */
@@ -762,6 +768,16 @@ gst_props_copy_on_write (GstProps *props)
   return new;
 }
 
+/**
+ * gst_props_get_entry:
+ * @props: the props to query
+ * @name: the name of the entry to get
+ *
+ * Get the props entry with the geven name
+ *
+ * Returns: The props entry with the geven name or NULL when
+ * the entry was not found.
+ */
 const GstPropsEntry*
 gst_props_get_entry (GstProps *props, const gchar *name)
 {
@@ -783,12 +799,31 @@ gst_props_get_entry (GstProps *props, const gchar *name)
   return NULL;
 }
 
+/**
+ * gst_props_has_property:
+ * @props: the props to check
+ * @name: the name of the key to find
+ *
+ * Checks if a given props has a property with the given name.
+ *
+ * Returns: TRUE if the property was found, FALSE otherwise.
+ */
 gboolean
 gst_props_has_property (GstProps *props, const gchar *name)
 {
   return (gst_props_get_entry (props, name) != NULL);
 }
 
+/**
+ * gst_props_has_property_typed:
+ * @props: the props to check
+ * @name: the name of the key to find
+ * @type: the type of the required property
+ *
+ * Checks if a given props has a property with the given name and the given type.
+ *
+ * Returns: TRUE if the property was found, FALSE otherwise.
+ */
 gboolean
 gst_props_has_property_typed (GstProps *props, const gchar *name, GstPropsType type)
 {
@@ -801,6 +836,16 @@ gst_props_has_property_typed (GstProps *props, const gchar *name, GstPropsType t
   return (entry->propstype == type);
 }
 
+/**
+ * gst_props_has_fixed_property:
+ * @props: the props to check
+ * @name: the name of the key to find
+ *
+ * Checks if a given props has a property with the given name that 
+ * is also fixed, ie. is not a list or a range.
+ *
+ * Returns: TRUE if the property was found, FALSE otherwise.
+ */
 gboolean
 gst_props_has_fixed_property (GstProps *props, const gchar *name)
 {
@@ -813,6 +858,14 @@ gst_props_has_fixed_property (GstProps *props, const gchar *name)
   return !GST_PROPS_ENTRY_IS_VARIABLE (entry);
 }
 
+/**
+ * gst_props_entry_get_type:
+ * @entry: the props entry to query
+ *
+ * Get the type of the given props entry. 
+ *
+ * Returns: The type of the props entry.
+ */
 GstPropsType
 gst_props_entry_get_type (const GstPropsEntry *entry)
 {
@@ -821,6 +874,14 @@ gst_props_entry_get_type (const GstPropsEntry *entry)
   return entry->propstype;
 }
 
+/**
+ * gst_props_entry_get_name:
+ * @entry: the props entry to query
+ *
+ * Get the name of the given props entry. 
+ *
+ * Returns: The name of the props entry.
+ */
 const gchar*
 gst_props_entry_get_name (const GstPropsEntry *entry)
 {
@@ -829,6 +890,15 @@ gst_props_entry_get_name (const GstPropsEntry *entry)
   return g_quark_to_string (entry->propid);
 }
 
+/**
+ * gst_props_entry_is_fixed:
+ * @entry: the props entry to query
+ *
+ * Checks if the props entry is fixe, ie. is not a list
+ * or a range.
+ *
+ * Returns: TRUE is the props entry is fixed.
+ */
 gboolean
 gst_props_entry_is_fixed (const GstPropsEntry *entry)
 {
@@ -847,6 +917,15 @@ gst_props_entry_getv (const GstPropsEntry *entry, gboolean safe, va_list var_arg
   return result;
 }
 
+/**
+ * gst_props_entry_get:
+ * @entry: the props entry to query
+ * @...: a pointer to a type that can hold the value.
+ *
+ * Gets the contents of the entry.
+ *
+ * Returns: TRUE is the props entry could be fetched.
+ */
 gboolean
 gst_props_entry_get (const GstPropsEntry *entry, ...)
 {
@@ -877,6 +956,16 @@ gst_props_entry_get_safe (const GstPropsEntry *entry, ...)
   return result;
 }
 
+/**
+ * gst_props_get:
+ * @props: the props to query
+ * @first_name: the first key
+ * @...: a pointer to a datastructure that can hold the value.
+ *
+ * Gets the contents of the props into given key/value pairs.
+ *
+ * Returns: TRUE is the props entry could be fetched.
+ */
 gboolean
 gst_props_get (GstProps *props, gchar *first_name, ...)
 {
@@ -899,55 +988,136 @@ gst_props_get (GstProps *props, gchar *first_name, ...)
   return TRUE;
 }
 
+/**
+ * gst_props_entry_get_int:
+ * @entry: the props entry to query
+ * @val: a pointer to a gint to hold the value.
+ *
+ * Get the contents of the entry into the given gint.
+ *
+ * Returns: TRUE is the value could be fetched. FALSE if the 
+ * entry is not of given type.
+ */
 gboolean
 gst_props_entry_get_int (const GstPropsEntry *entry, gint *val)
 {
   return gst_props_entry_get_safe (entry, GST_PROPS_INT_TYPE, val);
 }
 
+/**
+ * gst_props_entry_get_float:
+ * @entry: the props entry to query
+ * @val: a pointer to a gfloat to hold the value.
+ *
+ * Get the contents of the entry into the given gfloat.
+ *
+ * Returns: TRUE is the value could be fetched. FALSE if the 
+ * entry is not of given type.
+ */
 gboolean
 gst_props_entry_get_float (const GstPropsEntry *entry, gfloat *val)
 {
   return gst_props_entry_get_safe (entry, GST_PROPS_FLOAT_TYPE, val);
 }
 
+/**
+ * gst_props_entry_get_fourcc_int:
+ * @entry: the props entry to query
+ * @val: a pointer to a guint32 to hold the value.
+ *
+ * Get the contents of the entry into the given guint32.
+ *
+ * Returns: TRUE is the value could be fetched. FALSE if the 
+ * entry is not of given type.
+ */
 gboolean
 gst_props_entry_get_fourcc_int (const GstPropsEntry *entry, guint32 *val)
 {
   return gst_props_entry_get_safe (entry, GST_PROPS_FOURCC_TYPE, val);
 }
 
+/**
+ * gst_props_entry_get_boolean:
+ * @entry: the props entry to query
+ * @val: a pointer to a gboolean to hold the value.
+ *
+ * Get the contents of the entry into the given gboolean.
+ *
+ * Returns: TRUE is the value could be fetched. FALSE if the 
+ * entry is not of given type.
+ */
 gboolean
 gst_props_entry_get_boolean (const GstPropsEntry *entry, gboolean *val)
 {
   return gst_props_entry_get_safe (entry, GST_PROPS_BOOL_TYPE, val);
 }
 
+/**
+ * gst_props_entry_get_string:
+ * @entry: the props entry to query
+ * @val: a pointer to a gchar* to hold the value.
+ *
+ * Get the contents of the entry into the given gchar*.
+ *
+ * Returns: TRUE is the value could be fetched. FALSE if the 
+ * entry is not of given type.
+ */
 gboolean
 gst_props_entry_get_string (const GstPropsEntry *entry, const gchar **val)
 {
   return gst_props_entry_get_safe (entry, GST_PROPS_STRING_TYPE, val);
 }
 
+/**
+ * gst_props_entry_get_int_range:
+ * @entry: the props entry to query
+ * @min: a pointer to a gint to hold the minimun value.
+ * @max: a pointer to a gint to hold the maximum value.
+ *
+ * Get the contents of the entry into the given gints.
+ *
+ * Returns: TRUE is the value could be fetched. FALSE if the 
+ * entry is not of given type.
+ */
 gboolean
 gst_props_entry_get_int_range (const GstPropsEntry *entry, gint *min, gint *max)
 {
   return gst_props_entry_get_safe (entry, GST_PROPS_INT_RANGE_TYPE, min, max);
 }
 
+/**
+ * gst_props_entry_get_float_range:
+ * @entry: the props entry to query
+ * @min: a pointer to a gfloat to hold the minimun value.
+ * @max: a pointer to a gfloat to hold the maximum value.
+ *
+ * Get the contents of the entry into the given gfloats.
+ *
+ * Returns: TRUE is the value could be fetched. FALSE if the 
+ * entry is not of given type.
+ */
 gboolean
 gst_props_entry_get_float_range (const GstPropsEntry *entry, gfloat *min, gfloat *max)
 {
   return gst_props_entry_get_safe (entry, GST_PROPS_FLOAT_RANGE_TYPE, min, max);
 }
 
+/**
+ * gst_props_entry_get_list:
+ * @entry: the props entry to query
+ * @val: a pointer to a GList to hold the value.
+ *
+ * Get the contents of the entry into the given GList.
+ *
+ * Returns: TRUE is the value could be fetched. FALSE if the 
+ * entry is not of given type.
+ */
 gboolean
 gst_props_entry_get_list (const GstPropsEntry *entry, const GList **val)
 {
   return gst_props_entry_get_safe (entry, GST_PROPS_LIST_TYPE, val);
 }
 
-
 /**
  * gst_props_merge:
  * @props: the property to merge into
@@ -1495,6 +1665,15 @@ end:
   return intersection;
 }
 
+/**
+ * gst_props_normalize:
+ * @props: a property
+ *
+ * Unrolls all lists in the given GstProps. This is usefull if you
+ * want to loop over the props.
+ *
+ * Returns: A GList with the unrolled props entries.
+ */
 GList*
 gst_props_normalize (GstProps *props)
 {

gst/gstprops.h

@@ -113,7 +113,7 @@ GstPropsType		gst_props_entry_get_type	(const GstPropsEntry *entry);
 const gchar*		gst_props_entry_get_name	(const GstPropsEntry *entry);
 gboolean		gst_props_entry_is_fixed	(const GstPropsEntry *entry);
 
-gboolean		gst_props_entry_get		(const GstPropsEntry *props, ...);
+gboolean		gst_props_entry_get		(const GstPropsEntry *entry, ...);
 
 gboolean		gst_props_entry_get_int		(const GstPropsEntry *entry, gint *val);
 gboolean		gst_props_entry_get_float	(const GstPropsEntry *entry, gfloat *val);

gst/gstscheduler.c

@@ -193,7 +193,7 @@ gst_scheduler_add_element (GstScheduler *sched, GstElement *element)
 /**
  * gst_scheduler_remove_element:
  * @sched: the schedulerr
- * @element: the element to remov
+ * @element: the element to remove
  *
  * Remove an element from the schedulerr.
  */
@@ -270,6 +270,13 @@ gst_scheduler_state_transition (GstScheduler *sched, GstElement *element, gint t
   return GST_STATE_SUCCESS;
 }
 
+/**
+ * gst_scheduler_add_scheduler:
+ * @sched: the schedulerr
+ * @sched2: the scheduler to add
+ *
+ a Notifies the scheduler that it has to monitor this scheduler.
+ */
 void
 gst_scheduler_add_scheduler (GstScheduler *sched, GstScheduler *sched2)
 {
@@ -283,6 +290,13 @@ gst_scheduler_add_scheduler (GstScheduler *sched, GstScheduler *sched2)
     CLASS (sched)->add_scheduler (sched, sched2);
 }
 
+/**
+ * gst_scheduler_remove_scheduler:
+ * @sched: the schedulerr
+ * @sched2: the scheduler to remove
+ *
+ a Notifies the scheduler that it can stop monitoring this scheduler.
+ */
 void
 gst_scheduler_remove_scheduler (GstScheduler *sched, GstScheduler *sched2)
 {
@@ -296,7 +310,6 @@ gst_scheduler_remove_scheduler (GstScheduler *sched, GstScheduler *sched2)
     CLASS (sched)->remove_scheduler (sched, sched2);
 }
 
-
 /**
  * gst_scheduler_lock_element:
  * @sched: the scheduler
@@ -387,6 +400,14 @@ gst_scheduler_interrupt (GstScheduler *sched, GstElement *element)
   return FALSE;
 }
 
+/**
+ * gst_scheduler_get_clock:
+ * @sched: the scheduler
+ *
+ * Get the current clock used by the scheduler
+ *
+ * Returns: a GstClock
+ */
 GstClock*
 gst_scheduler_get_clock (GstScheduler *sched)
 {
@@ -420,6 +441,15 @@ gst_scheduler_get_clock (GstScheduler *sched)
   return clock;
 }
 
+/**
+ * gst_scheduler_use_clock:
+ * @sched: the scheduler
+ * @clock: the clock to use
+ *
+ * Force the scheduler to use the given clock. The scheduler will
+ * always use the given clock even if new clock providers are added
+ * to this scheduler.
+ */
 void
 gst_scheduler_use_clock (GstScheduler *sched, GstClock *clock)
 {
@@ -430,6 +460,14 @@ gst_scheduler_use_clock (GstScheduler *sched, GstClock *clock)
   sched->clock = clock;
 }
 
+/**
+ * gst_scheduler_set_clock:
+ * @sched: the scheduler
+ * @clock: the clock to set
+ *
+ * Set the clock for the scheduler. The clock will be distributed 
+ * to all the elements managed by the scheduler. 
+ */
 void
 gst_scheduler_set_clock (GstScheduler *sched, GstClock *clock)
 {
@@ -458,6 +496,12 @@ gst_scheduler_set_clock (GstScheduler *sched, GstClock *clock)
   }
 }
 
+/**
+ * gst_scheduler_auto_clock:
+ * @sched: the scheduler
+ *
+ * Let the scheduler select a clock automatically.
+ */
 void
 gst_scheduler_auto_clock (GstScheduler *sched)
 {
@@ -471,10 +515,13 @@ gst_scheduler_auto_clock (GstScheduler *sched)
 /**
  * gst_scheduler_clock_wait:
  * @sched: the scheduler
+ * @element: the element that wants to wait
+ * @clock: the clock to use
+ * @time: the time to wait for
  *
- * Perform one iteration on the schedulerr.
+ * Wait till the clock reaches a specific time
  *
- * Returns: a boolean indicating something usefull has happened.
+ * Returns: the status of the operation
  */
 GstClockReturn
 gst_scheduler_clock_wait (GstScheduler *sched, GstElement *element, GstClock *clock, GstClockTime time)

gst/gstsystemclock.c

@@ -87,6 +87,13 @@ gst_system_clock_init (GstSystemClock *clock)
 {
 }
 
+/**
+ * gst_system_clock_obtain 
+ *
+ * Get a handle to the default system clock.
+ *
+ * Returns: the default clock.
+ */
 GstClock*
 gst_system_clock_obtain (void)
 {

gst/gstxml.c

@@ -56,7 +56,7 @@ gst_xml_get_type(void)
       (GInstanceInitFunc)gst_xml_init,
       NULL
     };
-    xml_type = g_type_register_static (GST_TYPE_OBJECT, "GstXml", &xml_info, 0);
+    xml_type = g_type_register_static (GST_TYPE_OBJECT, "GstXML", &xml_info, 0);
   }
   return xml_type;
 }

plugins/elements/gstfakesink.c

@@ -266,8 +266,7 @@ gst_fakesink_chain (GstPad *pad, GstBuffer *buf)
 
   g_signal_emit (G_OBJECT (fakesink), gst_fakesink_signals[SIGNAL_HANDOFF], 0, buf, pad);
 
-  if (fakesink->dump)
+  if (fakesink->dump) {
-  {
     gst_util_dump_mem (GST_BUFFER_DATA (buf), GST_BUFFER_SIZE (buf));
   }
 

plugins/elements/gstidentity.c

@@ -51,6 +51,7 @@ enum {
   ARG_DROP_PROBABILITY,
   ARG_SILENT,
   ARG_LAST_MESSAGE,
+  ARG_DUMP,
 };
 
 
@@ -116,6 +117,9 @@ gst_identity_class_init (GstIdentityClass *klass)
   g_object_class_install_property (G_OBJECT_CLASS (klass), ARG_LAST_MESSAGE,
     g_param_spec_string ("last-message", "last-message", "last-message",
                          NULL, G_PARAM_READABLE)); 
+  g_object_class_install_property (G_OBJECT_CLASS (klass), ARG_DUMP,
+    g_param_spec_boolean("dump","Dump","Dump buffer contents",
+                         FALSE, G_PARAM_READWRITE));
 
   gst_identity_signals[SIGNAL_HANDOFF] =
     g_signal_new ("handoff", G_TYPE_FROM_CLASS(klass), G_SIGNAL_RUN_LAST,
@@ -174,6 +178,7 @@ gst_identity_init (GstIdentity *identity)
   identity->error_after = -1;
   identity->drop_probability = 0.0;
   identity->silent = FALSE;
+  identity->dump = FALSE;
 }
 
 static void 
@@ -206,6 +211,9 @@ gst_identity_chain (GstPad *pad, GstBuffer *buf)
       return;
     }
   }
+  if (identity->dump) {
+    gst_util_dump_mem (GST_BUFFER_DATA (buf), GST_BUFFER_SIZE (buf));
+  }
 
   for (i = identity->duplicate; i; i--) {
     if (!identity->silent)
@@ -275,6 +283,9 @@ gst_identity_set_property (GObject *object, guint prop_id, const GValue *value,
     case ARG_DUPLICATE:
       identity->duplicate = g_value_get_uint (value);
       break;
+    case ARG_DUMP:
+      identity->dump = g_value_get_boolean (value);
+      break;
     case ARG_ERROR_AFTER:
       identity->error_after = g_value_get_uint (value);
       break;
@@ -313,6 +324,9 @@ static void gst_identity_get_property(GObject *object, guint prop_id, GValue *va
     case ARG_SILENT:
       g_value_set_boolean (value, identity->silent);
       break;
+    case ARG_DUMP:
+      g_value_set_boolean (value, identity->dump);
+      break;
     case ARG_LAST_MESSAGE:
       g_value_set_string (value, identity->last_message);
       break;

plugins/elements/gstidentity.h

@@ -63,6 +63,7 @@ struct _GstIdentity {
   gfloat drop_probability;
   guint sleep_time;
   gboolean silent;
+  gboolean dump;
   gchar *last_message;
 };