diff --git a/gio/glistmodel.c b/gio/glistmodel.c
index 349b08be2..819b35374 100644
--- a/gio/glistmodel.c
+++ b/gio/glistmodel.c
@@ -31,74 +31,72 @@
 G_DEFINE_INTERFACE (GListModel, g_list_model, G_TYPE_OBJECT)
 
 /**
- * SECTION:glistmodel
- * @title: GListModel
- * @short_description: An interface describing a dynamic list of objects
- * @include: gio/gio.h
- * @see_also: #GListStore
+ * GListModel:
  *
- * #GListModel is an interface that represents a mutable list of
- * #GObjects. Its main intention is as a model for various widgets in
- * user interfaces, such as list views, but it can also be used as a
+ * `GListModel` is an interface that represents a mutable list of
+ * [class@GObject.Object]. Its main intention is as a model for various widgets
+ * in user interfaces, such as list views, but it can also be used as a
  * convenient method of returning lists of data, with support for
  * updates.
  *
  * Each object in the list may also report changes in itself via some
- * mechanism (normally the #GObject::notify signal).  Taken together
- * with the #GListModel::items-changed signal, this provides for a list
- * that can change its membership, and in which the members can change
- * their individual properties.
+ * mechanism (normally the [signal@GObject.Object::notify] signal).  Taken
+ * together with the [signal@Gio.ListModel::items-changed] signal, this provides
+ * for a list that can change its membership, and in which the members can
+ * change their individual properties.
  *
  * A good example would be the list of visible wireless network access
  * points, where each access point can report dynamic properties such as
  * signal strength.
  *
- * It is important to note that the #GListModel itself does not report
+ * It is important to note that the `GListModel` itself does not report
  * changes to the individual items.  It only reports changes to the list
  * membership.  If you want to observe changes to the objects themselves
  * then you need to connect signals to the objects that you are
  * interested in.
  *
- * All items in a #GListModel are of (or derived from) the same type.
- * g_list_model_get_item_type() returns that type.  The type may be an
+ * All items in a `GListModel` are of (or derived from) the same type.
+ * [method@Gio.ListModel.get_item_type] returns that type.  The type may be an
  * interface, in which case all objects in the list must implement it.
  *
  * The semantics are close to that of an array:
- * g_list_model_get_n_items() returns the number of items in the list and
- * g_list_model_get_item() returns an item at a (0-based) position. In
- * order to allow implementations to calculate the list length lazily,
+ * [method@Gio.ListModel.get_n_items] returns the number of items in the list
+ * and [method@Gio.ListModel.get_item] returns an item at a (0-based) position.
+ * In order to allow implementations to calculate the list length lazily,
  * you can also iterate over items: starting from 0, repeatedly call
- * g_list_model_get_item() until it returns %NULL.
+ * [method@Gio.ListModel.get_item] until it returns `NULL`.
  *
  * An implementation may create objects lazily, but must take care to
  * return the same object for a given position until all references to
  * it are gone.
  *
  * On the other side, a consumer is expected only to hold references on
- * objects that are currently "user visible", in order to facilitate the
+ * objects that are currently ‘user visible’, in order to facilitate the
  * maximum level of laziness in the implementation of the list and to
  * reduce the required number of signal connections at a given time.
  *
  * This interface is intended only to be used from a single thread.  The
  * thread in which it is appropriate to use it depends on the particular
  * implementation, but typically it will be from the thread that owns
- * the [thread-default main context][g-main-context-push-thread-default]
- * in effect at the time that the model was created.
+ * the thread-default main context (see
+ * [method@GLib.MainContext.push_thread_default]) in effect at the time that the
+ * model was created.
  *
- * Over time, it has established itself as good practice for listmodel
+ * Over time, it has established itself as good practice for list model
  * implementations to provide properties `item-type` and `n-items` to
  * ease working with them. While it is not required, it is recommended
  * that implementations provide these two properties. They should return
- * the values of g_list_model_get_item_type() and g_list_model_get_n_items()
- * respectively and be defined as such:
- * |[<!-- language="C" -->
+ * the values of [method@Gio.ListModel.get_item_type] and
+ * [method@Gio.ListModel.get_n_items] respectively and be defined as such:
+ *
+ * ```c
  * properties[PROP_ITEM_TYPE] =
  *   g_param_spec_gtype ("item-type", "", "", G_TYPE_OBJECT,
  *                       G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
  * properties[PROP_N_ITEMS] =
  *   g_param_spec_uint ("n-items", "", "", 0, G_MAXUINT, 0,
  *                      G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
- * ]|
+ * ```
  */
 
 /**
@@ -131,13 +129,6 @@ G_DEFINE_INTERFACE (GListModel, g_list_model, G_TYPE_OBJECT)
  * Since: 2.44
  */
 
-/**
- * GListModel:
- *
- * #GListModel is an opaque data structure and can only be accessed
- * using the following functions.
- **/
-
 static guint g_list_model_changed_signal;
 
 static void