diff --git a/gio/gdatagrambased.c b/gio/gdatagrambased.c
index f8de3728f..36223a280 100644
--- a/gio/gdatagrambased.c
+++ b/gio/gdatagrambased.c
@@ -32,57 +32,56 @@
 #include "glibintl.h"
 
 /**
- * SECTION:gdatagrambased
- * @short_description: Low-level datagram communications interface
- * @include: gio/gio.h
- * @see_also: #GSocket, [<gnetworking.h>][gio-gnetworking.h]
+ * GDatagramBased:
  *
- * A #GDatagramBased is a networking interface for representing datagram-based
+ * Interface for socket-like objects with datagram semantics.
+ *
+ * A `GDatagramBased` is a networking interface for representing datagram-based
  * communications. It is a more or less direct mapping of the core parts of the
  * BSD socket API in a portable GObject interface. It is implemented by
- * #GSocket, which wraps the UNIX socket API on UNIX and winsock2 on Windows.
+ * [struct@Gio.Socket], which wraps the UNIX socket API on UNIX and winsock2 on Windows.
  *
- * #GDatagramBased is entirely platform independent, and is intended to be used
- * alongside higher-level networking APIs such as #GIOStream.
+ * `GDatagramBased` is entirely platform independent, and is intended to be used
+ * alongside higher-level networking APIs such as [struct@Gio.IOStream].
  *
  * It uses vectored scatter/gather I/O by default, allowing for many messages
  * to be sent or received in a single call. Where possible, implementations of
  * the interface should take advantage of vectored I/O to minimise processing
- * or system calls. For example, #GSocket uses recvmmsg() and sendmmsg() where
- * possible. Callers should take advantage of scatter/gather I/O (the use of
+ * or system calls. For example, `GSocket` uses `recvmmsg()` and `sendmmsg()`
+ * where possible. Callers should take advantage of scatter/gather I/O (the use of
  * multiple buffers per message) to avoid unnecessary copying of data to
  * assemble or disassemble a message.
  *
- * Each #GDatagramBased operation has a timeout parameter which may be negative
+ * Each `GDatagramBased` operation has a timeout parameter which may be negative
  * for blocking behaviour, zero for non-blocking behaviour, or positive for
  * timeout behaviour. A blocking operation blocks until finished or there is an
  * error. A non-blocking operation will return immediately with a
- * %G_IO_ERROR_WOULD_BLOCK error if it cannot make progress. A timeout operation
+ * `G_IO_ERROR_WOULD_BLOCK` error if it cannot make progress. A timeout operation
  * will block until the operation is complete or the timeout expires; if the
  * timeout expires it will return what progress it made, or
- * %G_IO_ERROR_TIMED_OUT if no progress was made. To know when a call would
- * successfully run you can call g_datagram_based_condition_check() or
- * g_datagram_based_condition_wait(). You can also use
- * g_datagram_based_create_source() and attach it to a #GMainContext to get
- * callbacks when I/O is possible.
+ * `G_IO_ERROR_TIMED_OUT` if no progress was made. To know when a call would
+ * successfully run you can call [method@Gio.DatagramBased.condition_check] or
+ * [method@Gio.DatagramBased.condition_wait]. You can also use
+ * [method@Gio.DatagramBased.create_source] and attach it to a [struct@Glib.MainContext]
+ * to get callbacks when I/O is possible.
  *
  * When running a non-blocking operation applications should always be able to
- * handle getting a %G_IO_ERROR_WOULD_BLOCK error even when some other function
+ * handle getting a `G_IO_ERROR_WOULD_BLOCK` error even when some other function
  * said that I/O was possible. This can easily happen in case of a race
  * condition in the application, but it can also happen for other reasons. For
  * instance, on Windows a socket is always seen as writable until a write
- * returns %G_IO_ERROR_WOULD_BLOCK.
+ * returns `G_IO_ERROR_WOULD_BLOCK`.
  *
- * As with #GSocket, #GDatagramBaseds can be either connection oriented (for
- * example, SCTP) or connectionless (for example, UDP). #GDatagramBaseds must be
+ * As with `GSocket`, `GDatagramBased`s can be either connection oriented (for
+ * example, SCTP) or connectionless (for example, UDP). `GDatagramBased`s must be
  * datagram-based, not stream-based. The interface does not cover connection
  * establishment — use methods on the underlying type to establish a connection
- * before sending and receiving data through the #GDatagramBased API. For
+ * before sending and receiving data through the `GDatagramBased` API. For
  * connectionless socket types the target/source address is specified or
  * received in each I/O operation.
  *
- * Like most other APIs in GLib, #GDatagramBased is not inherently thread safe.
- * To use a #GDatagramBased concurrently from multiple threads, you must
+ * Like most other APIs in GLib, `GDatagramBased` is not inherently thread safe.
+ * To use a `GDatagramBased` concurrently from multiple threads, you must
  * implement your own locking.
  *
  * Since: 2.48
diff --git a/gio/gdatagrambased.h b/gio/gdatagrambased.h
index 585728c3f..aa2a1f221 100644
--- a/gio/gdatagrambased.h
+++ b/gio/gdatagrambased.h
@@ -41,13 +41,6 @@ G_BEGIN_DECLS
 #define G_TYPE_IS_DATAGRAM_BASED(type)    (g_type_is_a ((type), \
                                            G_TYPE_DATAGRAM_BASED))
 
-/**
- * GDatagramBased:
- *
- * Interface for socket-like objects with datagram semantics.
- *
- * Since: 2.48
- */
 typedef struct _GDatagramBasedInterface GDatagramBasedInterface;
 
 /**