diff --git a/gio/gasyncresult.c b/gio/gasyncresult.c
index 4d2f5f944..198a274e1 100644
--- a/gio/gasyncresult.c
+++ b/gio/gasyncresult.c
@@ -27,42 +27,40 @@
 
 
 /**
- * SECTION:gasyncresult
- * @short_description: Asynchronous Function Results
- * @include: gio/gio.h
- * @see_also: #GTask
+ * GAsyncResult:
  *
- * Provides a base class for implementing asynchronous function results.
+ * `GAsyncResult` provides a base class for implementing asynchronous function results.
  *
  * 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
+ * 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 must be run in a later iteration of
- * the [thread-default main context][g-main-context-push-thread-default]
- * from where the operation was initiated. It 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()"
+ * the thread-default main context (see
+ * [method@GLib.MainContext.push_thread_default]) from where the operation was
+ * initiated. It 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, passing the object the function was called for, the
- * #GAsyncResult instance, and (optionally) an @error to grab any
+ * `GAsyncResult` instance, and (optionally) an @error to grab any
  * error conditions that may have occurred.
  *
- * The "_finish()" function for an operation takes the generic result
- * (of type #GAsyncResult) and returns the specific result that the
- * operation in question yields (e.g. a #GFileEnumerator for a
+ * The `_finish()` function for an operation takes the generic result
+ * (of type `GAsyncResult`) and returns the specific result that the
+ * operation in question yields (e.g. a [struct@Gio.FileEnumerator] 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()"
+ * 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. You can pass
- * %NULL for the #GAsyncReadyCallback if you don't need to take any
+ * information after the `GAsyncReadyCallback` returns. You can pass
+ * `NULL` for the `GAsyncReadyCallback` if you don't need to take any
  * action at all after the operation completes. Applications may also
- * take a reference to the #GAsyncResult and call "_finish()" later;
- * however, the "_finish()" function may be called at most once.
+ * take a reference to the `GAsyncResult` and call `_finish()` later;
+ * however, the `_finish()` function may be called at most once.
  *
  * Example of a typical asynchronous operation flow:
- * |[<!-- language="C" -->
+ *
+ * ```c
  * void _theoretical_frobnitz_async (Theoretical         *t,
  *                                   GCancellable        *c,
  *                                   GAsyncReadyCallback  cb,
@@ -101,20 +99,20 @@
  *
  *    ...
  * }
- * ]|
+ * ```
  *
  * The callback for an asynchronous operation is called only once, and is
  * always called, even in the case of a cancelled operation. On cancellation
- * the result is a %G_IO_ERROR_CANCELLED error.
+ * the result is a `G_IO_ERROR_CANCELLED` error.
  *
- * ## I/O Priority # {#io-priority}
+ * ## I/O Priority
  *
  * Many I/O-related asynchronous operations have a priority parameter,
  * which is used in certain cases to determine the order in which
  * operations are executed. They are not used to determine system-wide
  * I/O scheduling. Priorities are integers, with lower numbers indicating
  * higher priority. It is recommended to choose priorities between
- * %G_PRIORITY_LOW and %G_PRIORITY_HIGH, with %G_PRIORITY_DEFAULT
+ * `G_PRIORITY_LOW` and `G_PRIORITY_HIGH`, with `G_PRIORITY_DEFAULT`
  * as a default.
  */
 
diff --git a/gio/gasyncresult.h b/gio/gasyncresult.h
index 4a98c5f44..17c79d442 100644
--- a/gio/gasyncresult.h
+++ b/gio/gasyncresult.h
@@ -36,12 +36,6 @@ G_BEGIN_DECLS
 #define G_IS_ASYNC_RESULT(obj)	       (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_ASYNC_RESULT))
 #define G_ASYNC_RESULT_GET_IFACE(obj)  (G_TYPE_INSTANCE_GET_INTERFACE ((obj), G_TYPE_ASYNC_RESULT, GAsyncResultIface))
 
-/**
- * GAsyncResult:
- *
- * Holds results information for an asynchronous operation,
- * usually passed directly to an asynchronous _finish() operation.
- **/
 typedef struct _GAsyncResultIface    GAsyncResultIface;