[totem-pl-parser] Added examples of async parsing to documentation

[Philip Withnall <pwithnall src gnome org>]

commit c4bbd33ab23e4b738ddd4512d91257eaca69dd22
Author: Philip Withnall <philip tecnocode co uk>
Date:   Mon Jun 22 17:51:32 2009 +0100

    Added examples of async parsing to documentation
    
    2009-06-22  Philip Withnall  <philip tecnocode co uk>
    
    	* plparse/totem-pl-parser.c: Added examples of async parsing, and
    	clarified in documentation that a main loop is now required for
    	totem-pl-parser to operate properly.

 ChangeLog                 |    6 ++++++
 plparse/totem-pl-parser.c |   27 ++++++++++++++++++++++++++-
 2 files changed, 32 insertions(+), 1 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 5cbb1cb..a5103f2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2009-06-22  Philip Withnall  <philip tecnocode co uk>
+
+	* plparse/totem-pl-parser.c: Added examples of async parsing, and
+	clarified in documentation that a main loop is now required for
+	totem-pl-parser to operate properly.
+
 2009-06-17  Philip Withnall  <philip tecnocode co uk>
 
 	* docs/reference/totem-pl-parser-sections.txt:
diff --git a/plparse/totem-pl-parser.c b/plparse/totem-pl-parser.c
index 45924ff..e768ad8 100644
--- a/plparse/totem-pl-parser.c
+++ b/plparse/totem-pl-parser.c
@@ -27,7 +27,8 @@
  * @include: totem-pl-parser.h
  *
  * #TotemPlParser is a general-purpose playlist parser and writer, with
- * support for several different types of playlist.
+ * support for several different types of playlist. Note that totem-pl-parser requires a main loop
+ * to operate properly (e.g. for the #TotemPlParser::entry-parsed signal to be emitted).
  *
  * <example>
  *  <title>Reading a Playlist</title>
@@ -44,6 +45,29 @@
  *  </programlisting>
  * </example>
  *
+  * <example>
+ *  <title>Reading a Playlist Asynchronously</title>
+ *  <programlisting>
+ * TotemPlParser *pl = totem_pl_parser_new ();
+ * g_object_set (pl, "recurse", FALSE, "disable-unsafe", TRUE, NULL);
+ * g_signal_connect (G_OBJECT (pl), "playlist-started", G_CALLBACK (playlist_started), NULL);
+ * g_signal_connect (G_OBJECT (pl), "entry-parsed", G_CALLBACK (entry_parsed), NULL);
+ *
+ * totem_pl_parser_parse_async (pl, "http://example.com/playlist.pls";, FALSE, NULL, parse_cb, NULL);
+ * g_object_unref (pl);
+ *
+ * static void
+ * parse_cb (TotemPlParser *parser, GAsyncResult *result, gpointer user_data)
+ * {
+ *	GError *error = NULL;
+ * 	if (totem_pl_parser_parse_finish (parser, result, &error) != TOTEM_PL_PARSER_RESULT_SUCCESS) {
+ * 		g_error ("Playlist parsing failed: %s", error->message);
+ * 		g_error_free (error);
+ * 	}
+ * }
+ *  </programlisting>
+ * </example>
+ *
  * <example>
  *  <title>Getting Metadata from Entries</title>
  *  <programlisting>
@@ -59,6 +83,7 @@
  *  </programlisting>
  * </example>
  *
+ *
  * <example>
  *  <title>Writing a Playlist</title>
  *  <programlisting>