- * </refsect2>
- * <refsect2>
- * <title>Porting from <literal>GSimpleAsyncResult</literal></title>
- * <para>
- * #GTask's API attempts to be simpler than #GSimpleAsyncResult's
- * in several ways:
- * </para>
- * <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>
- * <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>
- * <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
- * g_simple_async_result_set_check_cancellable() is called.
- * (You can use g_task_set_check_cancellable() to turn off that
- * behavior.) On the other hand, g_task_run_in_thread()
- * guarantees that it will always run your
- * <literal>task_func</literal>, even if the task's #GCancellable
- * is already cancelled before the task gets a chance to run;
- * 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>
- * <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>
- * <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>
- * <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
- * returns. This behavior is deprecated, because it makes it
- * difficult for a subclass to chain to a parent class's async
- * methods. Instead, the wrapper function should just be a
- * simple wrapper, and the virtual method should call an
- * appropriate <literal>g_task_propagate_</literal> function.
- * Note that wrapper methods can now use
- * g_async_result_legacy_propagate_error() to do old-style
- * #GSimpleAsyncResult error-returning behavior, and
- * g_async_result_is_tagged() to check if a result is tagged as
- * 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>
+ *
+ * ## Porting from GSimpleAsyncResult
+ *
+ * #GTask's API attempts to be simpler than #GSimpleAsyncResult's
+ * in several ways:
+ * - 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.
+ * - In addition to the task data, #GTask also keeps track of the
+ * [priority][io-priority], #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.
+ * - 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
+ * g_simple_async_result_set_check_cancellable() is called.
+ * (You can use g_task_set_check_cancellable() to turn off that
+ * behavior.) On the other hand, g_task_run_in_thread()
+ * guarantees that it will always run your
+ * `task_func`, even if the task's #GCancellable
+ * is already cancelled before the task gets a chance to run;
+ * you can start your `task_func` with a
+ * g_task_return_error_if_cancelled() check if you need the
+ * old behavior.
+ * - 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.)
+ * - 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.
+ * - With #GSimpleAsyncResult, it was common to call
+ * g_simple_async_result_propagate_error() from the
+ * `_finish()` wrapper function, and have
+ * virtual method implementations only deal with successful
+ * returns. This behavior is deprecated, because it makes it
+ * difficult for a subclass to chain to a parent class's async
+ * methods. Instead, the wrapper function should just be a
+ * simple wrapper, and the virtual method should call an
+ * appropriate `g_task_propagate_` function.
+ * Note that wrapper methods can now use
+ * g_async_result_legacy_propagate_error() to do old-style
+ * #GSimpleAsyncResult error-returning behavior, and
+ * g_async_result_is_tagged() to check if a result is tagged as
+ * having come from the `_async()` wrapper
+ * function (for "short-circuit" results, such as when passing
+ * 0 to g_input_stream_read_async()).