gst/: Small cleanups and doc updates.

Original commit message from CVS:
* gst/gstbus.c: (gst_bus_pop):
* gst/gstclock.c:
* gst/gstsystemclock.c: (gst_system_clock_async_thread):
Small cleanups and doc updates.

ChangeLog

@@ -1,3 +1,10 @@
+2005-10-08  Wim Taymans  <wim@fluendo.com>
+
+	* gst/gstbus.c: (gst_bus_pop):
+	* gst/gstclock.c:
+	* gst/gstsystemclock.c: (gst_system_clock_async_thread):
+	Small cleanups and doc updates.
+
 2005-10-08  Thomas Vander Stichele  <thomas at apestaart dot org>
 
 	* gst/gst.c: (init_pre):

gst/gstbus.c

@@ -33,6 +33,9 @@
  * 
  * The GstBus provides support for #GSource based notifications. This makes it
  * possible to handle the delivery in the glib mainloop.
+ *
+ * The #GSource callback function gst_bus_async_signal_func() can be used to
+ * convert all bus messages into signal emissions.
  * 
  * A message is posted on the bus with the gst_bus_post() method. With the
  * gst_bus_peek() and _pop() methods one can look at or retrieve a previously
@@ -52,9 +55,9 @@
  * message on the bus. This should only be used if the application is able
  * to deal with messages from different threads.
  *
- * Every #GstBin has one bus.
+ * Every #GstPipeline has one bus.
  *
- * Note that a #GstBin will set its bus into flushing state when changing from
+ * Note that a #GstPipeline will set its bus into flushing state when changing from
  * READY to NULL state.
  */
 
@@ -455,18 +458,15 @@ gst_bus_pop (GstBus * bus)
 
   g_return_val_if_fail (GST_IS_BUS (bus), NULL);
 
-  GST_DEBUG_OBJECT (bus, "%d messages on the bus",
-      g_queue_get_length (bus->queue));
-
   g_mutex_lock (bus->queue_lock);
   message = g_queue_pop_head (bus->queue);
-  g_mutex_unlock (bus->queue_lock);
-
   if (message)
-    GST_DEBUG_OBJECT (bus, "pop on bus, got message %p, %s", message,
+    GST_DEBUG_OBJECT (bus, "pop from bus, have %d messages, got message %p, %s",
+        g_queue_get_length (bus->queue) + 1, message,
         gst_message_type_get_name (GST_MESSAGE_TYPE (message)));
   else
-    GST_DEBUG_OBJECT (bus, "pop on bus, no message");
+    GST_DEBUG_OBJECT (bus, "pop from bus, no messages");
+  g_mutex_unlock (bus->queue_lock);
 
   return message;
 }

gst/gstclock.c

@@ -554,7 +554,8 @@ gst_clock_get_resolution (GstClock * clock)
  *
  * Converts the given @internal clock time to the real time, adjusting
  * and making sure that the returned time is increasing.
- * This function should be called with the clock lock held.
+ * This function should be called with the clock LOCK held and is
+ * mainly used by clock subclasses.
  *
  * Returns: the converted time of the clock.
  *

gst/gstsystemclock.c

@@ -230,14 +230,14 @@ gst_system_clock_async_thread (GstClock * clock)
   GST_LOCK (clock);
   /* signal spinup */
   GST_CLOCK_BROADCAST (clock);
-  /* now enter our infinite loop */
+  /* now enter our (almost) infinite loop */
   while (!sysclock->stopping) {
     GstClockEntry *entry;
     GstClockReturn res;
 
     /* check if something to be done */
     while (clock->entries == NULL) {
-      GST_CAT_DEBUG (GST_CAT_CLOCK, "nothing to wait for");
+      GST_CAT_DEBUG (GST_CAT_CLOCK, "no clock entries, waiting..");
       /* wait for work to do */
       GST_CLOCK_WAIT (clock);
       GST_CAT_DEBUG (GST_CAT_CLOCK, "got signal");
@@ -294,6 +294,8 @@ gst_system_clock_async_thread (GstClock * clock)
       default:
         GST_CAT_DEBUG (GST_CAT_CLOCK,
             "strange result %d waiting for %p, skipping", res, entry);
+        g_warning ("%s: strange result %d waiting for %p, skipping",
+            GST_OBJECT_NAME (clock), res, entry);
         goto next_entry;
     }
   next_entry:
@@ -337,6 +339,8 @@ gst_system_clock_get_resolution (GstClock * clock)
  * Entries that arrive too late are simply not waited on and a
  * GST_CLOCK_EARLY result is returned.
  *
+ * should be called with LOCK held.
+ *
  * MT safe.
  */
 static GstClockReturn