From d80f09239e328588e0e0a677a71c1ec321845ec8 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <matthiasc@src.gnome.org>
Date: Thu, 29 Nov 2007 20:35:23 +0000
Subject: [PATCH] More doc improvements

svn path=/trunk/; revision=5997
---
 gio/ChangeLog      |  5 ++++
 gio/gasyncresult.c | 66 ++++++++++++++++++++++++++++------------------
 2 files changed, 46 insertions(+), 25 deletions(-)

diff --git a/gio/ChangeLog b/gio/ChangeLog
index d7d47346..b25eb1d4 100644
--- a/gio/ChangeLog
+++ b/gio/ChangeLog
@@ -1,3 +1,8 @@
+2007-11-29  Matthias Clasen <mclasen@redhat.com>
+
+	* gasyncresult.c: Add another paragraph to the intro,
+	adjust coding style of example.
+
 2007-11-29  A. Walton <awalton@svn.gnome.org>
 
 	* gappinfo.c:
diff --git a/gio/gasyncresult.c b/gio/gasyncresult.c
index 5bba1137..a8950c9e 100644
--- a/gio/gasyncresult.c
+++ b/gio/gasyncresult.c
@@ -35,54 +35,70 @@
  * 
  * Asynchronous operations are broken up into two separate operations
  * which are chained together by a #GAsyncReadyCallback. To begin
- * an asynchronous operation, provide a #GAsyncReadyCallback to the asynchronous
- * function. This callback will be triggered when the operation has completed, 
- * and will be passed a #GAsyncReady instance filled with the details of the operation's
- * success or failure, the object the asynchronous function was 
- * started for and any error codes returned. The asynchronous callback function
- * is then expected to call the corresponding "_finish()" operation with the
- * object the function was called for, and the #GAsyncReady instance, and optionally, 
+ * an asynchronous operation, provide a #GAsyncReadyCallback to the 
+ * asynchronous function. This callback will be triggered when the 
+ * operation has completed, and will be passed a #GAsyncResult instance 
+ * filled with the details of the operation's success or failure, the 
+ * object the asynchronous function was started for and any error codes 
+ * returned. The asynchronous callback function is then expected to call 
+ * the corresponding "_finish()" function with the object the function 
+ * was called for, and the #GAsyncResult instance, and optionally, 
  * an @error to grab any error conditions that may have occurred.
  * 
+ * The purpose of the "_finish()" function is to take the generic 
+ * result of type #GAsyncResult and return the specific result
+ * that the operation in question yields (e.g. a #GFileEnumerator for
+ * a "enumerate children" operation). If the result or error status
+ * of the operation is not needed, there is no need to call the
+ * "_finish()" function, GIO will take care of cleaning up the
+ * result and error information after the #GAsyncReadyCallback 
+ * returns.
+ * 
  * Example of a typical asynchronous operation flow:
- * <informalexample>
- * <programlisting>
- * void _theoretical_frobnitz_async (Theoretical *t, 
- *                                   GCancellable *c, 
+ * |[
+ * void _theoretical_frobnitz_async (Theoretical         *t, 
+ *                                   GCancellable        *c, 
  *                                   GAsyncReadyCallback *cb,
- *                                   gpointer u);
+ *                                   gpointer             u);
  *
- * gboolean _theoretical_frobnitz_finish (Theoretical *t,
- *                                        GAsyncResult *res,
- *                                        GError **e);
+ * gboolean _theoretical_frobnitz_finish (Theoretical   *t,
+ *                                        GAsyncResult  *res,
+ *                                        GError       **e);
  *
  * static void 
- * frobnitz_result_func (GObject *source_object, 
+ * frobnitz_result_func (GObject      *source_object, 
  *			 GAsyncResult *res, 
- *			 gpointer user_data)
+ *			 gpointer      user_data)
  * {
  *   gboolean success = FALSE;
- *   success = _theoretical_frobnitz_finish( source_object, res, NULL );
+ *
+ *   success = _theoretical_frobnitz_finish (source_object, res, NULL);
+ *
  *   if (success)
- *     g_printf("Hurray!/n");
+ *     g_printf ("Hurray!/n");
  *   else 
- *     g_printf("Uh oh!/n");
+ *     g_printf ("Uh oh!/n");
+ *
  *   /<!-- -->* ... *<!-- -->/
- *   g_free(res);
+ *
+ *   g_free (res);
  * }
  *
  * int main (int argc, void *argv[])
  * {
  *    /<!-- -->* ... *<!-- -->/
- *    _theoretical_frobnitz_async (theoretical_data, NULL, frobnitz_result_func, NULL);
+ *
+ *    _theoretical_frobnitz_async (theoretical_data, 
+ *                                 NULL, 
+ *                                 frobnitz_result_func, 
+ *                                 NULL);
  *
  *    /<!-- -->* ... *<!-- -->/
- * </programlisting>
- * </informalexample> 
+ * }
+ * ]|
  * 
  * Asynchronous jobs are threaded if #GThread is available, but also may
  * be sent to the Main Event Loop and processed in an idle function.
- *
  **/
 
 static void g_async_result_base_init (gpointer g_class);
-- 
2.34.1