docs/manual/basics-bus.xml: Docs update: fix wrong callback return value explanation; add some lines about the implic...

Original commit message from CVS:
* docs/manual/basics-bus.xml:
Docs update: fix wrong callback return value explanation; add
some lines about the implicit relationship between main loop
and main context; remove duplicate main loop variable declaration.

ChangeLog

@@ -1,3 +1,10 @@
+2006-08-25  Tim-Philipp Müller  <tim at centricular dot net>
+
+	* docs/manual/basics-bus.xml:
+	  Docs update: fix wrong callback return value explanation; add
+	  some lines about the implicit relationship between main loop
+	  and main context; remove duplicate main loop variable declaration.
+
 2006-08-24  Tim-Philipp Müller  <tim at centricular dot net>
 
 	* tests/check/gst/gstcaps.c: (GST_START_TEST):

docs/manual/basics-bus.xml

@@ -60,6 +60,8 @@ my_bus_callback (GstBus     *bus,
 		 GstMessage *message,
 		 gpointer    data)
 {
+  g_print ("Got %s message\n", GST_MESSAGE_TYPE_NAME (message));
+
   switch (GST_MESSAGE_TYPE (message)) {
     case GST_MESSAGE_ERROR: {
       GError *err;
@@ -82,7 +84,10 @@ my_bus_callback (GstBus     *bus,
       break;
   }
 
-  /* remove message from the queue */
+  /* we want to be notified again the next time there is a message
+   * on the bus, so returning TRUE (FALSE means we want to stop watching
+   * for messages on the bus and our callback should not be called again)
+   */
   return TRUE;
 }
 
@@ -90,7 +95,6 @@ gint
 main (gint   argc,
       gchar *argv[])
 {
-  GMainLoop *loop;
   GstElement *pipeline;
   GstBus *bus;
 
@@ -99,17 +103,32 @@ main (gint   argc,
 
   /* create pipeline, add handler */
   pipeline = gst_pipeline_new ("my_pipeline");
+
+  /* adds a watch for new message on our pipeline's message bus to
+   * the default GLib main context, which is the main context that our
+   * GLib main loop is attached to below
+   */
   bus = gst_pipeline_get_bus (GST_PIPELINE (pipeline));
   gst_bus_add_watch (bus, my_bus_callback, NULL);
   gst_object_unref (bus);
 <!-- example-end bus.c a -->
 [..]<!-- example-begin bus.c b -->
 <!-- example-begin bus.c c -->
-  /* in the mainloop, all messages posted to the bus by the pipeline
+  /* create a mainloop that runs/iterates the default GLib main context
-   * will automatically be sent to our callback. */
+   * (context NULL), in other words: makes the context check if anything
+   * it watches for has happened. When a message has been posted on the
+   * bus, the default main context will automatically call our
+   * my_bus_callback() function to notify us of that message.
+   * The main loop will be run until someone calls g_main_loop_quit()
+   */
   loop = g_main_loop_new (NULL, FALSE);
   g_main_loop_run (loop);
 
+  /* clean up */
+  gst_element_set_state (pipeline, GST_STATE_NULL);
+  gst_element_unref (pipeline);
+  gst_main_loop_unref (loop)
+
   return 0;
 }
     <!-- example-end bus.c c -->