docs: Fix the GListModel descriptionlist-model-doc-fixes

- Isolate the first meaningful paragraph, for gi-docgen's summary
- Describe get_object() as a binding API
- Fix reference to get_item() inside get_item_type()

1 files changed, 23 insertions, 10 deletions

diff --git a/gio/glistmodel.c b/gio/glistmodel.c
index eb797caaf..42230758d 100644
--- a/gio/glistmodel.c
+++ b/gio/glistmodel.c
@@ -135,7 +135,7 @@ g_list_model_default_init (GListModelInterface *iface)
    * from @list. At @position, @removed items were removed and @added
    * items were added in their place.
    *
-   * Note: If @removed != @added, the positions of all later items
+   * Note: If `@removed != @added`, the positions of all later items
    * in the model change.
    *
    * Since: 2.44
@@ -157,9 +157,11 @@ g_list_model_default_init (GListModelInterface *iface)
  * g_list_model_get_item_type:
  * @list: a #GListModel
  *
- * Gets the type of the items in @list. All items returned from
- * g_list_model_get_type() are of that type or a subtype, or are an
- * implementation of that interface.
+ * Gets the type of the items in @list.
+ *
+ * All items returned from g_list_model_get_item() are of the type
+ * returned by this function, or a subtype, or if the type is an
+ * interface, they are an implementation of that interface.
  *
  * The item type of a #GListModel can not change during the life of the
  * model.
@@ -203,11 +205,15 @@ g_list_model_get_n_items (GListModel *list)
  * @list: a #GListModel
  * @position: the position of the item to fetch
  *
- * Get the item at @position. If @position is greater than the number of
- * items in @list, %NULL is returned.
+ * Get the item at @position.
+ *
+ * If @position is greater than the number of items in @list, %NULL is
+ * returned.
  *
  * %NULL is never returned for an index that is smaller than the length
- * of the list.  See g_list_model_get_n_items().
+ * of the list.
+ *
+ * See also: g_list_model_get_n_items()
  *
  * Returns: (transfer full) (nullable): the item at @position.
  *
@@ -227,11 +233,18 @@ g_list_model_get_item (GListModel *list,
  * @list: a #GListModel
  * @position: the position of the item to fetch
  *
- * Get the item at @position. If @position is greater than the number of
- * items in @list, %NULL is returned.
+ * Get the item at @position.
+ *
+ * If @position is greater than the number of items in @list, %NULL is
+ * returned.
  *
  * %NULL is never returned for an index that is smaller than the length
- * of the list.  See g_list_model_get_n_items().
+ * of the list.
+ *
+ * This function is meant to be used by language bindings in place
+ * of g_list_model_get_item().
+ *
+ * See also: g_list_model_get_n_items()
  *
  * Returns: (transfer full) (nullable): the object at @position.
  *