[gtk/matthiasc/for-master: 10/11] docs: Revise the filter docs a bit

[Matthias Clasen <matthiasc src gnome org>]

commit bcd650f169a587309b49fec830acd5dd96c4616f
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Jul 16 21:48:08 2020 -0400

    docs: Revise the filter docs a bit

 gtk/gtkcustomfilter.c    | 14 +++++++++-----
 gtk/gtkfilter.c          | 25 +++++++++++++------------
 gtk/gtkfilterlistmodel.c | 14 ++++++++++----
 gtk/gtkmultifilter.c     |  6 +++---
 gtk/gtkstringfilter.c    |  2 +-
 5 files changed, 36 insertions(+), 25 deletions(-)
---
diff --git a/gtk/gtkcustomfilter.c b/gtk/gtkcustomfilter.c
index d2ec8dc23a..13bcf86342 100644
--- a/gtk/gtkcustomfilter.c
+++ b/gtk/gtkcustomfilter.c
@@ -29,8 +29,8 @@
  * @Title: GtkCustomFilter
  * @Short_description: Filtering with callbacks
  *
- * #GtkCustomFilter is a #GtkFilter that uses a callback to determine whether
- * to include an item or not.
+ * #GtkCustomFilter is a #GtkFilter that uses a callback to determine
+ * whether to include an item or not.
  */
 struct _GtkCustomFilter
 {
@@ -98,11 +98,13 @@ gtk_custom_filter_init (GtkCustomFilter *self)
  * gtk_custom_filter_new:
  * @match_func: (nullable): function to filter items
  * @user_data: (nullable): user data to pass to @match_func
- * @user_destroy: destory notify
+ * @user_destroy: destroy notify for @user_data
  *
  * Creates a new filter using the given @match_func to filter
  * items.
  *
+ * If @match_func is %NULL, the filter matches all items.
+ *
  * If the filter func changes its filtering behavior,
  * gtk_filter_changed() needs to be called.
  *
@@ -127,10 +129,12 @@ gtk_custom_filter_new (GtkCustomFilterFunc match_func,
  * @self: a #GtkCustomFilter
  * @match_func: (nullable): function to filter 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 filtering items.
- * 
+ *
+ * If @match_func is %NULL, the filter matches all items.
+ *
  * If the filter func changes its filtering behavior,
  * gtk_filter_changed() needs to be called.
  *
diff --git a/gtk/gtkfilter.c b/gtk/gtkfilter.c
index 697359d74b..fc3d63efaf 100644
--- a/gtk/gtkfilter.c
+++ b/gtk/gtkfilter.c
@@ -30,20 +30,21 @@
  * @Short_description: Filtering items
  * @See_also: #GtkFilerListModel
  *
- * #GtkFilter is the way to describe filters to be used in #GtkFilterListModel.
- * 
- * The model will use a filter to determine if it should filter items or not
- * by calling gtk_filter_match() for each item and only keeping the ones
- * visible that the function returns %TRUE for.
+ * A #GtkFilter object describes the filtering to be performed by a
+ * #GtkFilterListModel.
+ *
+ * The model will use the filter to determine if it should include items
+ * or not by calling gtk_filter_match() for each item and only keeping the
+ * ones that the function returns %TRUE for.
  *
  * Filters may change what items they match through their lifetime. In that
- * case, they can call gtk_filter_changed() which will emit the #GtkFilter:changed
- * signal to notify that previous filter results are no longer valid and that
- * items should be checked via gtk_filter_match() again.
+ * case, they will emit the #GtkFilter:changed signal to notify that previous
+ * filter results are no longer valid and that items should be checked again
+ * via gtk_filter_match().
  *
- * GTK provides various premade filter implementations for common filtering
+ * GTK provides various pre-made filter implementations for common filtering
  * operations. These filters often include properties that can be linked to
- * various widgets to easily allow searches.  
+ * various widgets to easily allow searches.
  *
  * However, in particular for large lists or complex search methods, it is
  * also possible to subclass #GtkFilter and provide one's own filter.
@@ -118,7 +119,7 @@ gtk_filter_init (GtkFilter *self)
  * @self: a #GtkFilter
  * @item: (type GObject) (transfer none): The item to check
  *
- * Checks if the given @item is matched by the filter or not. 
+ * Checks if the given @item is matched by the filter or not.
  *
  * Returns: %TRUE if the filter matches the item and a filter model should
  *     keep it, %FALSE if not.
@@ -140,7 +141,7 @@ gtk_filter_match (GtkFilter *self,
  * Gets the known strictness of @filters. If the strictness is not known,
  * %GTK_FILTER_MATCH_SOME is returned.
  *
- * This value may change after emission of the GtkFilter:changed signal.
+ * This value may change after emission of the #GtkFilter:changed signal.
  *
  * This function is meant purely for optimization purposes, filters can
  * choose to omit implementing it, but #GtkFilterListModel uses it.
diff --git a/gtk/gtkfilterlistmodel.c b/gtk/gtkfilterlistmodel.c
index 387393cd69..a02ad57abf 100644
--- a/gtk/gtkfilterlistmodel.c
+++ b/gtk/gtkfilterlistmodel.c
@@ -771,8 +771,8 @@ gtk_filter_list_model_get_model (GtkFilterListModel *self)
  * @self: a #GtkFilterListModel
  * @incremental: %TRUE to enable incremental filtering
  *
- * When incremental filtering is enabled, the filterlistmodel will not run
- * filters immediately, but will instead queue an idle handler that
+ * When incremental filtering is enabled, the GtkFilterListModel will not
+ * run filters immediately, but will instead queue an idle handler that
  * incrementally filters the items and adds them to the list. This of course
  * means that items are not instantly added to the list, but only appear
  * incrementally.
@@ -837,8 +837,14 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self)
  *
  * You can use this value to check if @self is busy filtering by
  * comparing the return value to 0 or you can compute the percentage
- * of the filter remaining by dividing the return value by
- * g_list_model_get_n_items(gtk_filter_list_model_get_model (self)).
+ * of the filter remaining by dividing the return value by the total
+ * number of items in the underlying model:
+ *
+ * |[
+ *   pending = gtk_filter_list_model_get_pending (self);
+ *   model = gtk_filter_list_model_get_model (self);
+ *   percentage = pending / (double) g_list_model_get_n_items (model);
+ * ]|
  *
  * Returns: The number of items not yet filtered
  **/
diff --git a/gtk/gtkmultifilter.c b/gtk/gtkmultifilter.c
index 6fb08cc9da..8c8ac9c068 100644
--- a/gtk/gtkmultifilter.c
+++ b/gtk/gtkmultifilter.c
@@ -35,10 +35,10 @@
  * GtkMultiFilter is the base type that implements support for handling
  * multiple filters.
  *
- * GtkAnyFilter is an implementation of GtkMultiFilter that matches an item
+ * GtkAnyFilter is a subclass of GtkMultiFilter that matches an item
  * when at least one of its filters matches.
  *
- * GtkEveryFilter is an implementation of GtkMultiFilter that matches an item
+ * GtkEveryFilter is a subclass of GtkMultiFilter that matches an item
  * when each of its filters matches.
  */
 struct _GtkMultiFilter
@@ -413,7 +413,7 @@ gtk_every_filter_init (GtkEveryFilter *self)
 /**
  * gtk_every_filter_new:
  *
- * Creates a new empty "every" filter.  
+ * Creates a new empty "every" filter.
  * Use gtk_multi_filter_append() to add filters to it.
  *
  * This filter matches an item if each of the filters added to it
diff --git a/gtk/gtkstringfilter.c b/gtk/gtkstringfilter.c
index df45fe4f2a..2aed620f50 100644
--- a/gtk/gtkstringfilter.c
+++ b/gtk/gtkstringfilter.c
@@ -27,7 +27,7 @@
 /**
  * SECTION:gtkstringfilter
  * @Title: GtkStringFilter
- * @Short_description: Filtering by string
+ * @Short_description: Filtering by strings
  *
  * GtkStringFilter determines whether to include items by looking
  * at strings and comparing them to a fixed search term. The strings