From fd7f19c93442a9e0b5a299bb4b403c0e87906f86 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Sat, 6 Jun 2020 10:36:09 -0400
Subject: [PATCH] selectionmodel: Document the callback apis

---
 docs/reference/gtk/gtk4-sections.txt |  3 +++
 gtk/gtkselectionmodel.c              | 18 ++++++++++++++++++
 gtk/gtkselectionmodel.h              | 19 +++++++++++++++++++
 3 files changed, 40 insertions(+)

diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index ddd8b58de3..1e201c9694 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -350,6 +350,9 @@ gtk_selection_model_select_range
 gtk_selection_model_unselect_range
 gtk_selection_model_select_all
 gtk_selection_model_unselect_all
+GtkSelectionCallback
+gtk_selection_model_select_callback
+gtk_selection_model_unselect_callback
 gtk_selection_model_query_range
 <SUBSECTION>
 gtk_selection_model_selection_changed
diff --git a/gtk/gtkselectionmodel.c b/gtk/gtkselectionmodel.c
index dfbf167f9a..1bbf277d61 100644
--- a/gtk/gtkselectionmodel.c
+++ b/gtk/gtkselectionmodel.c
@@ -342,6 +342,15 @@ gtk_selection_model_unselect_all (GtkSelectionModel *model)
   return iface->unselect_all (model);
 }
 
+/**
+ * gtk_selection_model_select_callback:
+ * @model: a #GtkSelectionModel
+ * @callback: a #GtkSelectionCallback to determine items to select
+ * @data: data to pass to @callback
+ *
+ * Requests to select all items for which @callback returns
+ * @selected as TRUE.
+ */
 gboolean
 gtk_selection_model_select_callback (GtkSelectionModel    *model,
                                      GtkSelectionCallback  callback,
@@ -352,6 +361,15 @@ gtk_selection_model_select_callback (GtkSelectionModel    *model,
   return GTK_SELECTION_MODEL_GET_IFACE (model)->select_callback (model, callback, data);
 }
 
+/**
+ * gtk_selection_model_unselect_callback:
+ * @model: a #GtkSelectionModel
+ * @callback: a #GtkSelectionCallback to determine items to select
+ * @data: data to pass to @callback
+ *
+ * Requests to unselect all items for which @callback returns
+ * @selected as TRUE.
+ */
 gboolean
 gtk_selection_model_unselect_callback (GtkSelectionModel    *model,
                                        GtkSelectionCallback  callback,
diff --git a/gtk/gtkselectionmodel.h b/gtk/gtkselectionmodel.h
index 3a73572ac2..2a6318d6f2 100644
--- a/gtk/gtkselectionmodel.h
+++ b/gtk/gtkselectionmodel.h
@@ -33,6 +33,25 @@ G_BEGIN_DECLS
 GDK_AVAILABLE_IN_ALL
 G_DECLARE_INTERFACE (GtkSelectionModel, gtk_selection_model, GTK, SELECTION_MODEL, GListModel)
 
+/**
+ * GtkSelectionCallback:
+ * @position: the position to query
+ * @start_range: (out): returns the position of the first element of the range
+ * @n_items: (out): returns the size of the range
+ * @selected: (out): returns whether items in @range are selected
+ * @data: callback data
+ *
+ * Callback type for determining items to operate on with
+ * gtk_selection_model_select_callback() or
+ * gtk_selection_model_unselect_callback().
+ *
+ * The callback determines a range of consecutive items around
+ * @position which should either all
+ * be changed, in which case @selected is set to %TRUE, or all not
+ * be changed, in which case @selected is set to %FALSE.
+ *
+ * @start_range and @n_items are set to return the range.
+ */
 typedef void     (* GtkSelectionCallback) (guint     position,
                                            guint    *start_range,
                                            guint    *n_items,