[gtk/doc-links: 5/6] docs: Unify docs around incremental operations

[Matthias Clasen <matthiasc src gnome org>]

commit 7972dc877634ee6f57e3b0f2d2f20a2c333d090f
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Aug 3 17:42:05 2020 -0400

    docs: Unify docs around incremental operations
    
    Sync up the wording around incremental filtering
    and sorting to be more similar.

 gtk/gtkfilterlistmodel.c |  8 ++++++--
 gtk/gtksortlistmodel.c   | 12 ++++++++++--
 2 files changed, 16 insertions(+), 4 deletions(-)
---
diff --git a/gtk/gtkfilterlistmodel.c b/gtk/gtkfilterlistmodel.c
index 52d3c860d9..9d943fb2ae 100644
--- a/gtk/gtkfilterlistmodel.c
+++ b/gtk/gtkfilterlistmodel.c
@@ -786,6 +786,9 @@ gtk_filter_list_model_get_model (GtkFilterListModel *self)
  * interesting around 10,000 to 100,000 items.
  *
  * By default, incremental filtering is disabled.
+ *
+ * See gtk_filter_list_model_get_pending() for progress information
+ * about an ongoing incremental filtering operation.
  **/
 void
 gtk_filter_list_model_set_incremental (GtkFilterListModel *self,
@@ -837,8 +840,6 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self)
  *
  * Returns the number of items that have not been filtered yet.
  *
- * When incremental filtering is not enabled, this always returns 0.
- *
  * 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 the total
@@ -850,6 +851,9 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self)
  *   percentage = pending / (double) g_list_model_get_n_items (model);
  * ]|
  *
+ * If no filter operation is ongoing - in particular when
+ * #GtkFilterListModel:incremental is %FALSE - this function returns 0.
+ *
  * Returns: The number of items not yet filtered
  **/
 guint
diff --git a/gtk/gtksortlistmodel.c b/gtk/gtksortlistmodel.c
index 24c2b5271d..8f758d46cf 100644
--- a/gtk/gtksortlistmodel.c
+++ b/gtk/gtksortlistmodel.c
@@ -61,6 +61,10 @@
  * #GtkSortListModel is a list model that takes a list model and
  * sorts its elements according to a #GtkSorter.
  *
+ * The model can be set up to do incremental sorting, so that
+ * sorting long lists doesn't block the UI. See
+ * gtk_sort_list_model_set_incremental() for details.
+ *
  * #GtkSortListModel is a generic model and because of that it
  * cannot take advantage of any external knowledge when sorting.
  * If you run into performance issues with #GtkSortListModel, it
@@ -978,6 +982,9 @@ gtk_sort_list_model_get_sorter (GtkSortListModel *self)
  * interesting around 10,000 to 100,000 items.
  *
  * By default, incremental sorting is disabled.
+ *
+ * See gtk_sort_list_model_get_pending() for progress information
+ * about an ongoing incremental sorting operation.
  */
 void
 gtk_sort_list_model_set_incremental (GtkSortListModel *self,
@@ -1032,8 +1039,9 @@ gtk_sort_list_model_get_incremental (GtkSortListModel *self)
  *
  * If you want to estimate the progress, you can use code like this:
  * |[<!-- language="C" -->
- * double progress = 1.0 - (double) gtk_sort_list_model_get_pending (self) 
- *                         / MAX (1, g_list_model_get_n_items (G_LIST_MODEL (sort)));
+ *   pending = gtk_sort_list_model_get_pending (self);
+ *   model = gtk_sort_list_model_get_model (self);
+ *   progress = 1.0 - pending / (double) MAX (1, g_list_model_get_n_items (model));
  * ]|
  *
  * If no sort operation is ongoing - in particular when