More doc improvements

svn path=/trunk/; revision=5997

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:

gio/gasyncresult.c

@@ -35,18 +35,27 @@
  * 
  * 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
+ * an asynchronous operation, provide a #GAsyncReadyCallback to the 
- * function. This callback will be triggered when the operation has completed, 
+ * asynchronous function. This callback will be triggered when the 
- * and will be passed a #GAsyncReady instance filled with the details of the operation's
+ * operation has completed, and will be passed a #GAsyncResult instance 
- * success or failure, the object the asynchronous function was 
+ * filled with the details of the operation's success or failure, the 
- * started for and any error codes returned. The asynchronous callback function
+ * object the asynchronous function was started for and any error codes 
- * is then expected to call the corresponding "_finish()" operation with the
+ * returned. The asynchronous callback function is then expected to call 
- * object the function was called for, and the #GAsyncReady instance, and optionally, 
+ * 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, 
  *                                   GAsyncReadyCallback *cb,
@@ -62,27 +71,34 @@
  *			 gpointer      user_data)
  * {
  *   gboolean success = FALSE;
+ *
  *   success = _theoretical_frobnitz_finish (source_object, res, NULL);
+ *
  *   if (success)
  *     g_printf ("Hurray!/n");
  *   else 
  *     g_printf ("Uh oh!/n");
+ *
  *   /<!-- -->* ... *<!-- -->/
+ *
  *   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);