[gtk/misc-multiselection: 1/2] multiselection: Clarify docs

[Matthias Clasen <matthiasc src gnome org>]

commit de6327a885d4e981d88bf34a0351ce948b2d5553
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Jun 6 10:22:37 2020 -0400

    multiselection: Clarify docs
    
    Make it clear that GtkMultiSelection is not persistent
    across resorting.

 gtk/gtkmultiselection.c | 6 ++++++
 1 file changed, 6 insertions(+)
---
diff --git a/gtk/gtkmultiselection.c b/gtk/gtkmultiselection.c
index a97718e704..11caa78fc1 100644
--- a/gtk/gtkmultiselection.c
+++ b/gtk/gtkmultiselection.c
@@ -33,6 +33,12 @@
  *
  * GtkMultiSelection is an implementation of the #GtkSelectionModel interface
  * that allows selecting multiple elements.
+ *
+ * Note that due to the way the selection is stored, newly added items are
+ * always unselected, even if they were just removed from the model, and were
+ * selected before. In particular this means that changing the sort order of
+ * an underlying sort model will clear the selection. In other words, the
+ * selection is *not persistent*.
  */
 
 struct _GtkMultiSelection