GTask: convert long desc to markdown

Use markdown sections and lists here.

gio/gtask.c

@@ -30,12 +30,10 @@
  * @include: gio/gio.h
  * @see_also: #GAsyncResult
  *
- * <para>
  * A #GTask represents and manages a cancellable "task".
- * </para>
+ *
- * <refsect2>
+ * ## Asynchronous operations
- *   <title>Asynchronous operations</title>
+ *
- *   <para>
  * The most common usage of #GTask is as a #GAsyncResult, to
  * manage data during an asynchronous operation. You call
  * g_task_new() in the "start" method, followed by
@@ -50,7 +48,7 @@
  * to the operation's finish function (as a #GAsyncResult), and
  * you can use g_task_propagate_pointer() or the like to extract
  * the return value.
- *   </para>
+ *
  * Here is an example for using GTask as a GAsyncResult:
  * |[
  *     typedef struct {
@@ -145,10 +143,9 @@
  *       return g_task_propagate_pointer (G_TASK (result), error);
  *     }
  * ]|
- * </refsect2>
+ *
- * <refsect2>
+ * ## Chained asynchronous operations
- *   <title>Chained asynchronous operations</title>
+ *
- *   <para>
  * #GTask also tries to simplify asynchronous operations that
  * internally chain together several smaller asynchronous
  * operations. g_task_get_cancellable(), g_task_get_context(), and
@@ -159,8 +156,7 @@
  * g_task_attach_source() simplifies the case of waiting for a
  * source to fire (automatically using the correct #GMainContext
  * and priority).
- *   </para>
+ *
- *   <para>
  * Here is an example for chained asynchronous operations:
  *   |[
  *     typedef struct {
@@ -288,17 +284,14 @@
  *       return g_task_propagate_pointer (G_TASK (result), error);
  *     }
  * ]|
- * </para>
+ *
- * </refsect2>
+ * ## Asynchronous operations from synchronous ones
- * <refsect2>
+ *
- *   <title>Asynchronous operations from synchronous ones</title>
- *   <para>
  * You can use g_task_run_in_thread() to turn a synchronous
  * operation into an asynchronous one, by running it in a thread
  * which will then dispatch the result back to the caller's
  * #GMainContext when it completes.
- *   </para>
+ *
- *   <para>
  * Running a task in a thread:
  *   |[
  *     typedef struct {
@@ -368,11 +361,9 @@
  *       return g_task_propagate_pointer (G_TASK (result), error);
  *     }
  * ]|
- * </para>
+ *
- * </refsect2>
+ * ## Adding cancellability to uncancellable tasks
- * <refsect2>
+ * 
- *   <title>Adding cancellability to uncancellable tasks</title>
- *   <para>
  * Finally, g_task_run_in_thread() and g_task_run_in_thread_sync()
  * can be used to turn an uncancellable operation into a
  * cancellable one. If you call g_task_set_return_on_cancel(),
@@ -384,8 +375,7 @@
  * locks and other externally-visible resources, this allows you
  * to make "GLib-friendly" asynchronous and cancellable
  * synchronous variants of blocking APIs.
- *   </para>
+ *
- *   <para>
  * Cancelling a task:
  *   |[
  *     static void
@@ -439,7 +429,7 @@
  *                            GAsyncReadyCallback  callback,
  *                            gpointer             user_data)
  *     {
- *       CakeData *cake_data;
+ J*       CakeData *cake_data;
  *       GTask *task;
  *
  *       cake_data = g_slice_new (CakeData);
@@ -477,30 +467,21 @@
  *       return cake;
  *     }
  * ]|
- * </para>
+ *
- * </refsect2>
+ * ## Porting from GSimpleAsyncResult
- * <refsect2>
+ * 
- *   <title>Porting from <literal>GSimpleAsyncResult</literal></title>
- *   <para>
  * #GTask's API attempts to be simpler than #GSimpleAsyncResult's
  * in several ways:
- *   </para>
+ * - You can save task-specific data with g_task_set_task_data(), and
- *   <itemizedlist>
- *     <listitem><para>
- *       You can save task-specific data with g_task_set_task_data(), and
  *   retrieve it later with g_task_get_task_data(). This replaces the
  *   abuse of g_simple_async_result_set_op_res_gpointer() for the same
  *   purpose with #GSimpleAsyncResult.
- *     </para></listitem>
+ * - In addition to the task data, #GTask also keeps track of the
- *     <listitem><para>
- *       In addition to the task data, #GTask also keeps track of the
  *   <link linkend="io-priority">priority</link>, #GCancellable, and
  *   #GMainContext associated with the task, so tasks that consist of
  *   a chain of simpler asynchronous operations will have easy access
  *   to those values when starting each sub-task.
- *     </para></listitem>
+ * - g_task_return_error_if_cancelled() provides simplified
- *     <listitem><para>
- *       g_task_return_error_if_cancelled() provides simplified
  *   handling for cancellation. In addition, cancellation
  *   overrides any other #GTask return value by default, like
  *   #GSimpleAsyncResult does when
@@ -513,26 +494,20 @@
  *   you can start your <literal>task_func</literal> with a
  *   g_task_return_error_if_cancelled() check if you need the
  *   old behavior.
- *     </para></listitem>
+ * - The "return" methods (eg, g_task_return_pointer())
- *     <listitem><para>
- *       The "return" methods (eg, g_task_return_pointer())
  *   automatically cause the task to be "completed" as well, and
  *   there is no need to worry about the "complete" vs "complete
  *   in idle" distinction. (#GTask automatically figures out
  *   whether the task's callback can be invoked directly, or
  *   if it needs to be sent to another #GMainContext, or delayed
  *   until the next iteration of the current #GMainContext.)
- *     </para></listitem>
+ * - The "finish" functions for #GTask-based operations are generally
- *     <listitem><para>
- *       The "finish" functions for #GTask-based operations are generally
  *   much simpler than #GSimpleAsyncResult ones, normally consisting
  *   of only a single call to g_task_propagate_pointer() or the like.
  *   Since g_task_propagate_pointer() "steals" the return value from
  *   the #GTask, it is not necessary to juggle pointers around to
  *   prevent it from being freed twice.
- *     </para></listitem>
+ * - With #GSimpleAsyncResult, it was common to call
- *     <listitem><para>
- *       With #GSimpleAsyncResult, it was common to call
  *   g_simple_async_result_propagate_error() from the
  *   <literal>_finish()</literal> wrapper function, and have
  *   virtual method implementations only deal with successful
@@ -548,9 +523,6 @@
  *   having come from the <literal>_async()</literal> wrapper
  *   function (for "short-circuit" results, such as when passing
  *   0 to g_input_stream_read_async()).
- *     </para></listitem>
- *   </itemizedlist>
- * </refsect2>
  */
 
 /**