[gtk/matthiasc/for-master: 10/11] docs: Revise the filter docs a bit
- From: Matthias Clasen <matthiasc src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gtk/matthiasc/for-master: 10/11] docs: Revise the filter docs a bit
- Date: Fri, 17 Jul 2020 02:00:18 +0000 (UTC)
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
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]