[gtk/matthiasc/for-master: 9/11] docs: Revise sorter docs a bit

[Matthias Clasen <matthiasc src gnome org>]

commit 72d66dfcddaa7f8fefe13e16c1dc27721a075439
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Jul 16 21:45:11 2020 -0400

    docs: Revise sorter docs a bit

 docs/reference/gtk/gtk4-docs.xml |  2 +-
 gtk/gtkcustomsorter.c            | 14 +++++++++-----
 gtk/gtksorter.c                  |  5 ++---
 3 files changed, 12 insertions(+), 9 deletions(-)
---
diff --git a/docs/reference/gtk/gtk4-docs.xml b/docs/reference/gtk/gtk4-docs.xml
index 3e2751c6b7..6b5128ca2a 100644
--- a/docs/reference/gtk/gtk4-docs.xml
+++ b/docs/reference/gtk/gtk4-docs.xml
@@ -65,9 +65,9 @@
       <section>
         <xi:include href="xml/gtksorter.xml" />
         <xi:include href="xml/gtkcustomsorter.xml" />
+        <xi:include href="xml/gtkmultisorter.xml" />
         <xi:include href="xml/gtkstringsorter.xml" />
         <xi:include href="xml/gtknumericsorter.xml" />
-        <xi:include href="xml/gtkmultisorter.xml" />
       </section>
       <xi:include href="xml/gtkselectionmodel.xml" />
       <section>
diff --git a/gtk/gtkcustomsorter.c b/gtk/gtkcustomsorter.c
index 6359fd68b0..f1bddd954b 100644
--- a/gtk/gtkcustomsorter.c
+++ b/gtk/gtkcustomsorter.c
@@ -27,7 +27,7 @@
 /**
  * SECTION:gtkcustomsorter
  * @Title: GtkCustomSorter
- * @Short_description: Sorting with a callback
+ * @Short_description: Sorting with a callbacks
  *
  * GtkCustomSorter is a #GtkSorter implementation that sorts
  * via a traditional #GCompareDataFunc callback.
@@ -108,8 +108,10 @@ gtk_custom_sorter_init (GtkCustomSorter *self)
  * Creates a new #GtkSorter that works by calling
  * @sort_func to compare items.
  *
- * Returns: a new #GTkSorter
- */ 
+ * If @sort_func is %NULL, all items are considered equal.
+ *
+ * Returns: a new #GtkSorter
+ */
 GtkSorter *
 gtk_custom_sorter_new (GCompareDataFunc sort_func,
                        gpointer         user_data,
@@ -129,10 +131,12 @@ gtk_custom_sorter_new (GCompareDataFunc sort_func,
  * @self: a #GtkCustomSorter
  * @sort_func: (nullable): function to sort items
  * @user_data: (nullable): user data to pass to @match_func
- * @user_destroy: destory notify
+ * @user_destroy: destroy notify for @user_data
  *
  * Sets (or unsets) the function used for sorting items.
- * 
+ *
+ * If @sort_func is %NULL, all items are considered equal.
+ *
  * If the sort func changes its sorting behavior,
  * gtk_sorter_changed() needs to be called.
  *
diff --git a/gtk/gtksorter.c b/gtk/gtksorter.c
index 9169d22979..c07340870d 100644
--- a/gtk/gtksorter.c
+++ b/gtk/gtksorter.c
@@ -37,9 +37,8 @@
  * by calling gtk_sorter_compare() for pairs of items.
  *
  * Sorters may change their sorting behavior through their lifetime. In that case,
- * they call gtk_sorter_changed(), which will emit the #GtkSorter::changed signal to
- * notify that the sort order is no longer valid and should be updated by calling
- * gtk_sorter_compare() again.
+ * they will emit the #GtkSorter::changed signal to notify that the sort order is
+ * no longer valid and should be updated by calling gtk_sorter_compare() again.
  *
  * GTK provides various pre-made sorter implementations for common sorting operations.
  * #GtkColumnView has built-in support for sorting lists via the #GtkColumnViewColumn:sorter