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
- * @caps: the capabilities to use in the reconnectiong
+ * @srcpad: the source"pad to reconnect
+ * @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
- * @caps: the capabilities to use in the reconnectiong
+ * @srcpad: the source"pad to reconnect
+ * @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.
- * FIXME: no one calls this function. why is it here?
+ * Attempt to reconnect the pad to its peer through its filter, 
+ * 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,