[gtk/selection-model-docs] selectionmodel: Clarify docs

[Matthias Clasen <matthiasc src gnome org>]

commit 03d86012a7e19082f5fe52c8c6e23e7b7fcfe39b
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Jun 2 11:14:21 2020 -0400

    selectionmodel: Clarify docs
    
    Clarify some things that were not clear to me before
    discussing them.
    
    Fixes: #2806

 gtk/gtkselectionmodel.c | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)
---
diff --git a/gtk/gtkselectionmodel.c b/gtk/gtkselectionmodel.c
index 7be454fd74..e95fb06517 100644
--- a/gtk/gtkselectionmodel.c
+++ b/gtk/gtkselectionmodel.c
@@ -38,15 +38,20 @@
  * #GtkSingleSelection, so you will only need to implement this interface if you want
  * detailed control about how selections should be handled.
  *
- * A #GtkSelectionModel supports a single boolean per row indicating if a row is selected
+ * A #GtkSelectionModel supports a single boolean per item indicating if an item is selected
  * or not. This can be queried via gtk_selection_model_is_selected(). When the selected
- * state of one or more rows changes, the model will emit the
+ * state of one or more items changes, the model will emit the
  * #GtkSelectionModel::selection-changed signal by calling the
  * gtk_selection_model_selection_changed() function. The positions given in that signal
- * may have their selection state changed, though that is not a requirement.  
+ * may have their selection state changed, though that is not a requirement.
  * If new items added to the model via the #GListModel::items-changed signal are selected
  * or not is up to the implementation.
  *
+ * Note that you need to listen to both #GListModel::items-changed and to
+ * #GListModel::selection-changed to keep track of which items are selected.
+ * #GtkSelectionModel will generally only emit the one or the other signal, not
+ * both, to avoid ordering and reentrancy issues.
+ *
  * Additionally, the interface can expose functionality to select and unselect items.
  * If these functions are implemented, GTK's list widgets will allow users to select and
  * unselect items. However, #GtkSelectionModels are free to only implement them