[glib/list-model-doc-fixes] docs: Fix the GListModel description

[Emmanuele Bassi <ebassi src gnome org>]

commit d3b19d20c564e6b339114ca3741debd989f6cbd4
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Thu Sep 30 09:56:52 2021 +0100

    docs: Fix the GListModel description
    
    - 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()

 gio/glistmodel.c | 33 +++++++++++++++++++++++----------
 1 file changed, 23 insertions(+), 10 deletions(-)
---
diff --git a/gio/glistmodel.c b/gio/glistmodel.c
index eb797caaf..0411353c2 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.
  *