filters: Modernize the docs Remove gtk-docisms, apply more gi-docgen syntax, and reword things to be closer to the style recommended in https://developer.gnome.org/documentation/guidelines/devel-docs.html
diff --git a/gtk/gtkboolfilter.c b/gtk/gtkboolfilter.c index b35ebed..dca433c 100644 --- a/gtk/gtkboolfilter.c +++ b/gtk/gtkboolfilter.c
@@ -26,8 +26,7 @@ /** * GtkBoolFilter: * - * `GtkBoolFilter` evaluates a boolean `GtkExpression` - * to determine whether to include items. + * Evaluates a boolean expression to determine whether to include items. */ struct _GtkBoolFilter @@ -155,7 +154,7 @@ /** * GtkBoolFilter:expression: (type GtkExpression) * - * The boolean expression to evaluate on item. + * The boolean expression to evaluate on each item. */ properties[PROP_EXPRESSION] = gtk_param_spec_expression ("expression", NULL, NULL, @@ -181,7 +180,7 @@ /** * gtk_bool_filter_new: - * @expression: (transfer full) (nullable): The expression to evaluate + * @expression: (transfer full) (nullable): the expression to evaluate * * Creates a new bool filter. * @@ -203,12 +202,12 @@ /** * gtk_bool_filter_get_expression: - * @self: a `GtkBoolFilter` + * @self: a bool filter * - * Gets the expression that the filter uses to evaluate if - * an item should be filtered. + * Gets the expression that the filter evaluates for + * each item. * - * Returns: (transfer none) (nullable): a `GtkExpression` + * Returns: (transfer none) (nullable): the expression */ GtkExpression * gtk_bool_filter_get_expression (GtkBoolFilter *self) @@ -220,13 +219,13 @@ /** * gtk_bool_filter_set_expression: - * @self: a `GtkBoolFilter` - * @expression: (nullable): a `GtkExpression` + * @self: a bool filter + * @expression: (nullable): the expression * * Sets the expression that the filter uses to check if items * should be filtered. * - * The expression must have a value type of %G_TYPE_BOOLEAN. + * The expression must have a value type of `G_TYPE_BOOLEAN`. */ void gtk_bool_filter_set_expression (GtkBoolFilter *self, @@ -249,11 +248,11 @@ /** * gtk_bool_filter_get_invert: - * @self: a `GtkBoolFilter` + * @self: a bool filter * * Returns whether the filter inverts the expression. * - * Returns: %TRUE if the filter inverts + * Returns: true if the filter inverts */ gboolean gtk_bool_filter_get_invert (GtkBoolFilter *self) @@ -265,8 +264,8 @@ /** * gtk_bool_filter_set_invert: - * @self: a `GtkBoolFilter` - * @invert: %TRUE to invert + * @self: a bool filter + * @invert: true to invert * * Sets whether the filter should invert the expression. */
diff --git a/gtk/gtkcustomfilter.c b/gtk/gtkcustomfilter.c index 4dbd4a6..e06e463 100644 --- a/gtk/gtkcustomfilter.c +++ b/gtk/gtkcustomfilter.c
@@ -26,7 +26,7 @@ /** * GtkCustomFilter: * - * `GtkCustomFilter` determines whether to include items with a callback. + * Determines whether to include items with a callback. */ struct _GtkCustomFilter { @@ -96,13 +96,12 @@ * @user_data: (nullable): user data to pass to @match_func * @user_destroy: destroy notify for @user_data * - * Creates a new filter using the given @match_func to filter - * items. + * Creates a new filter using the given function to filter items. * - * If @match_func is %NULL, the filter matches all 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. + * [method@Gtk.Filter.changed] needs to be called. * * Returns: a new `GtkCustomFilter` **/ @@ -122,20 +121,20 @@ /** * gtk_custom_filter_set_filter_func: - * @self: a `GtkCustomFilter` + * @self: a custom filter * @match_func: (nullable): function to filter items * @user_data: (nullable): user data to pass to @match_func * @user_destroy: destroy notify for @user_data * * Sets the function used for filtering items. * - * If @match_func is %NULL, the filter matches all 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. + * [method@Gtk.Filter.changed] needs to be called. * - * If a previous function was set, its @user_destroy will be - * called now. + * If a previous function was set, its @user_destroy + * will be called. */ void gtk_custom_filter_set_filter_func (GtkCustomFilter *self,
diff --git a/gtk/gtkcustomfilter.h b/gtk/gtkcustomfilter.h index 08d5161..49206d5 100644 --- a/gtk/gtkcustomfilter.h +++ b/gtk/gtkcustomfilter.h
@@ -29,15 +29,15 @@ /** * GtkCustomFilterFunc: - * @item: (type GObject): The item to be matched + * @item: (type GObject): the item to be matched * @user_data: user data * * User function that is called to determine if the @item should be matched. * - * If the filter matches the item, this function must return %TRUE. If the - * item should be filtered out, %FALSE must be returned. + * If the filter matches the item, this function must return true. + * If the item should be filtered out, false must be returned. * - * Returns: %TRUE to keep the item around + * Returns: true to keep the item around */ typedef gboolean (* GtkCustomFilterFunc) (gpointer item, gpointer user_data);
diff --git a/gtk/gtkfilefilter.c b/gtk/gtkfilefilter.c index 71f45ef..b5025b0 100644 --- a/gtk/gtkfilefilter.c +++ b/gtk/gtkfilefilter.c
@@ -19,10 +19,10 @@ /** * GtkFileFilter: * - * `GtkFileFilter` filters files by name or mime type. + * Filters files by name or mime type. * * `GtkFileFilter` can be used to restrict the files being shown in a - * `GtkFileChooser`. Files can be filtered based on their name (with + * file chooser. Files can be filtered based on their name (with * [method@Gtk.FileFilter.add_pattern] or [method@Gtk.FileFilter.add_suffix]) * or on their mime type (with [method@Gtk.FileFilter.add_mime_type]). * @@ -32,8 +32,8 @@ * text/plain. Note that `GtkFileFilter` allows wildcards for the * subtype of a mime type, so you can e.g. filter for image/\*. * - * Normally, file filters are used by adding them to a `GtkFileChooser` - * (see [method@Gtk.FileChooser.add_filter]), but it is also possible to + * Normally, file filters are used by adding them to a file chooser + * (see [method@Gtk.FileDialog.set_filters]), but it is also possible to * manually use a file filter on any [class@Gtk.FilterListModel] containing * `GFileInfo` objects. * @@ -259,8 +259,8 @@ * * The human-readable name of the filter. * - * This is the string that will be displayed in the file chooser - * user interface if there is a selectable list of filters. + * This is the string that will be displayed in the user interface + * if there is a selectable list of filters. */ props[PROP_NAME] = g_param_spec_string ("name", NULL, NULL, @@ -534,13 +534,12 @@ /** * gtk_file_filter_set_name: - * @filter: a `GtkFileFilter` - * @name: (nullable): the human-readable-name for the filter, or %NULL - * to remove any existing name. + * @filter: a file filter + * @name: (nullable): the human-readable name for the filter * * Sets a human-readable name of the filter. * - * This is the string that will be displayed in the file chooser + * This is the string that will be displayed in the user interface * if there is a selectable list of filters. */ void @@ -560,13 +559,13 @@ /** * gtk_file_filter_get_name: - * @filter: a `GtkFileFilter` + * @filter: a file filter * * Gets the human-readable name for the filter. * * See [method@Gtk.FileFilter.set_name]. * - * Returns: (nullable): The human-readable name of the filter + * Returns: (nullable): the human-readable name of the filter */ const char * gtk_file_filter_get_name (GtkFileFilter *filter) @@ -607,10 +606,10 @@ /** * gtk_file_filter_add_mime_type: - * @filter: A `GtkFileFilter` + * @filter: A file filter * @mime_type: name of a MIME type * - * Adds a rule allowing a given mime type to @filter. + * Adds a rule allowing a given mime type. */ void gtk_file_filter_add_mime_type (GtkFileFilter *filter, @@ -632,10 +631,10 @@ /** * gtk_file_filter_add_pattern: - * @filter: a `GtkFileFilter` - * @pattern: a shell style glob + * @filter: a file filter + * @pattern: a shell style glob pattern * - * Adds a rule allowing a shell style glob to a filter. + * Adds a rule allowing a shell style glob pattern. * * Note that it depends on the platform whether pattern * matching ignores case or not. On Windows, it does, on @@ -660,13 +659,12 @@ /** * gtk_file_filter_add_suffix: - * @filter: a `GtkFileFilter` + * @filter: a file filter * @suffix: filename suffix to match * * Adds a suffix match rule to a filter. * - * This is similar to adding a match for the pattern - * "*.@suffix". + * This is similar to adding a match for the pattern "*.@suffix". * * In contrast to pattern matches, suffix matches * are *always* case-insensitive. @@ -692,10 +690,9 @@ /** * gtk_file_filter_add_pixbuf_formats: - * @filter: a `GtkFileFilter` + * @filter: a file filter * - * Adds a rule allowing image files in the formats supported - * by GdkPixbuf. + * Adds a rule allowing image files in the formats supported by `GdkPixbuf`. * * This is equivalent to calling [method@Gtk.FileFilter.add_mime_type] * for all the supported mime types. @@ -739,14 +736,13 @@ /** * gtk_file_filter_get_attributes: - * @filter: a `GtkFileFilter` + * @filter: a file filter * * Gets the attributes that need to be filled in for the `GFileInfo` * passed to this filter. * * This function will not typically be used by applications; - * it is intended principally for use in the implementation - * of `GtkFileChooser`. + * it is intended for use in file chooser implementation. * * Returns: (transfer none): the attributes */ @@ -956,7 +952,7 @@ /** * gtk_file_filter_to_gvariant: - * @filter: a `GtkFileFilter` + * @filter: a file filter * * Serialize a file filter to an `a{sv}` variant. *
diff --git a/gtk/gtkfilter.c b/gtk/gtkfilter.c index 0a1c5b4..74d9262 100644 --- a/gtk/gtkfilter.c +++ b/gtk/gtkfilter.c
@@ -27,12 +27,11 @@ /** * GtkFilter: * - * A `GtkFilter` object describes the filtering to be performed by a - * [class@Gtk.FilterListModel]. + * Describes the filtering to be performed by a [class@Gtk.FilterListModel]. * * The model will use the filter to determine if it should include items * or not by calling [method@Gtk.Filter.match] for each item and only - * keeping the ones that the function returns %TRUE for. + * keeping the ones that the function returns true for. * * Filters may change what items they match through their lifetime. In that * case, they will emit the [signal@Gtk.Filter::changed] signal to notify @@ -81,7 +80,7 @@ /** * GtkFilter::changed: - * @self: The `GtkFilter` + * @self: the filter * @change: how the filter changed * * Emitted whenever the filter changed. @@ -116,13 +115,12 @@ /** * gtk_filter_match: - * @self: a `GtkFilter` + * @self: a filter * @item: (type GObject) (transfer none): The item to check * * 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. + * Returns: true if the filter matches the item */ gboolean gtk_filter_match (GtkFilter *self, @@ -136,16 +134,16 @@ /** * gtk_filter_get_strictness: - * @self: a `GtkFilter` + * @self: a filter * - * Gets the known strictness of @filters. + * Gets the known strictness of a filter. * - * If the strictness is not known, %GTK_FILTER_MATCH_SOME is returned. + * If the strictness is not known, [enum@Gtk.FilterMatch.some] is returned. * * This value may change after emission of the [signal@Gtk.Filter::changed] * signal. * - * This function is meant purely for optimization purposes, filters can + * This function is meant purely for optimization purposes. Filters can * choose to omit implementing it, but `GtkFilterListModel` uses it. * * Returns: the strictness of @self @@ -160,8 +158,8 @@ /** * gtk_filter_changed: - * @self: a `GtkFilter` - * @change: How the filter changed + * @self: a filter + * @change: how the filter changed * * Notifies all users of the filter that it has changed. * @@ -184,4 +182,3 @@ g_signal_emit (self, signals[CHANGED], 0, change); } -
diff --git a/gtk/gtkfilter.h b/gtk/gtkfilter.h index 140ba14..eee00b9 100644 --- a/gtk/gtkfilter.h +++ b/gtk/gtkfilter.h
@@ -30,16 +30,16 @@ /** * GtkFilterMatch: * @GTK_FILTER_MATCH_SOME: The filter matches some items, - * gtk_filter_match() may return %TRUE or %FALSE + * [method@Gtk.Filter.match] may return true or false * @GTK_FILTER_MATCH_NONE: The filter does not match any item, - * gtk_filter_match() will always return %FALSE. + * [method@Gtk.Filter.match] will always return false * @GTK_FILTER_MATCH_ALL: The filter matches all items, - * gtk_filter_match() will alays return %TRUE. + * [method@Gtk.Filter.match] will alays return true * * Describes the known strictness of a filter. * * Note that for filters where the strictness is not known, - * %GTK_FILTER_MATCH_SOME is always an acceptable value, + * `GTK_FILTER_MATCH_SOME` is always an acceptable value, * even if a filter does match all or no items. */ typedef enum { @@ -51,19 +51,19 @@ /** * GtkFilterChange: * @GTK_FILTER_CHANGE_DIFFERENT: The filter change cannot be - * described with any of the other enumeration values. + * described with any of the other enumeration values * @GTK_FILTER_CHANGE_LESS_STRICT: The filter is less strict than - * it was before: All items that it used to return %TRUE for - * still return %TRUE, others now may, too. + * it was before: All items that it used to return true + * still return true, others now may, too. * @GTK_FILTER_CHANGE_MORE_STRICT: The filter is more strict than - * it was before: All items that it used to return %FALSE for - * still return %FALSE, others now may, too. + * it was before: All items that it used to return false + * still return false, others now may, too. * * Describes changes in a filter in more detail and allows objects * using the filter to optimize refiltering items. * * If you are writing an implementation and are not sure which - * value to pass, %GTK_FILTER_CHANGE_DIFFERENT is always a correct + * value to pass, `GTK_FILTER_CHANGE_DIFFERENT` is always a correct * choice. */ typedef enum {
diff --git a/gtk/gtkmultifilter.c b/gtk/gtkmultifilter.c index da44510..41bf720 100644 --- a/gtk/gtkmultifilter.c +++ b/gtk/gtkmultifilter.c
@@ -36,13 +36,13 @@ /** * GtkMultiFilter: * - * `GtkMultiFilter` is the base class for filters that combine multiple filters. + * Base class for filters that combine multiple filters. */ /** * GtkAnyFilter: * - * `GtkAnyFilter` matches an item when at least one of its filters matches. + * Matches an item when at least one of its filters matches. * * To add filters to a `GtkAnyFilter`, use [method@Gtk.MultiFilter.append]. */ @@ -50,7 +50,7 @@ /** * GtkEveryFilter: * - * `GtkEveryFilter` matches an item when each of its filters matches. + * Matches an item when each of its filters matches. * * To add filters to a `GtkEveryFilter`, use [method@Gtk.MultiFilter.append]. */ @@ -200,10 +200,12 @@ /** * GtkMultiFilter:item-type: * - * The type of items. See [method@Gio.ListModel.get_item_type]. + * The type of items. + * + * See [method@Gio.ListModel.get_item_type]. * * Since: 4.8 - **/ + */ properties[PROP_ITEM_TYPE] = g_param_spec_gtype ("item-type", NULL, NULL, GTK_TYPE_FILTER, @@ -212,10 +214,12 @@ /** * GtkMultiFilter:n-items: * - * The number of items. See [method@Gio.ListModel.get_n_items]. + * The number of items. + * + * See [method@Gio.ListModel.get_n_items]. * * Since: 4.8 - **/ + */ properties[PROP_N_ITEMS] = g_param_spec_uint ("n-items", NULL, NULL, 0, G_MAXUINT, 0, @@ -232,10 +236,10 @@ /** * gtk_multi_filter_append: - * @self: a `GtkMultiFilter` - * @filter: (transfer full): A new filter to use + * @self: a multi filter + * @filter: (transfer full): a filter to add * - * Adds a @filter to @self to use for matching. + * Adds a filter. */ void gtk_multi_filter_append (GtkMultiFilter *self, @@ -255,14 +259,13 @@ /** * gtk_multi_filter_remove: - * @self: a `GtkMultiFilter` + * @self: a multi filter * @position: position of filter to remove * - * Removes the filter at the given @position from the list of filters used - * by @self. + * Removes a filter. * - * If @position is larger than the number of filters, nothing happens and - * the function returns. + * If @position is larger than the number of filters, + * nothing happens. **/ void gtk_multi_filter_remove (GtkMultiFilter *self,
diff --git a/gtk/gtkstringfilter.c b/gtk/gtkstringfilter.c index 20ee042..6b4b669 100644 --- a/gtk/gtkstringfilter.c +++ b/gtk/gtkstringfilter.c
@@ -26,10 +26,9 @@ /** * GtkStringFilter: * - * `GtkStringFilter` determines whether to include items by comparing - * strings to a fixed search term. + * Determines whether to include items by comparing strings to a fixed search term. * - * The strings are obtained from the items by evaluating a `GtkExpression` + * The strings are obtained from the items by evaluating an expression * set with [method@Gtk.StringFilter.set_expression], and they are * compared against a search term set with [method@Gtk.StringFilter.set_search]. * @@ -249,7 +248,8 @@ /** * GtkStringFilter:expression: (type GtkExpression) * - * The expression to evaluate on item to get a string to compare with. + * The expression to evaluate on each item to get a + * string to compare with. */ properties[PROP_EXPRESSION] = gtk_param_spec_expression ("expression", NULL, NULL, @@ -299,7 +299,7 @@ /** * gtk_string_filter_new: - * @expression: (transfer full) (nullable): The expression to evaluate + * @expression: (transfer full) (nullable): the expression to evaluate * * Creates a new string filter. * @@ -324,11 +324,11 @@ /** * gtk_string_filter_get_search: - * @self: a `GtkStringFilter` + * @self: a string filter * * Gets the search term. * - * Returns: (nullable) (transfer none): The search term + * Returns: (nullable) (transfer none): the search term **/ const char * gtk_string_filter_get_search (GtkStringFilter *self) @@ -340,9 +340,8 @@ /** * gtk_string_filter_set_search: - * @self: a `GtkStringFilter` - * @search: (transfer none) (nullable): The string to search for - * or %NULL to clear the search + * @self: a string filter + * @search: (transfer none) (nullable): the string to search for * * Sets the string to search for. */ @@ -381,12 +380,12 @@ /** * gtk_string_filter_get_expression: - * @self: a `GtkStringFilter` + * @self: a string filter * * Gets the expression that the string filter uses to * obtain strings from items. * - * Returns: (transfer none) (nullable): a `GtkExpression` + * Returns: (transfer none) (nullable): the expression */ GtkExpression * gtk_string_filter_get_expression (GtkStringFilter *self) @@ -398,13 +397,13 @@ /** * gtk_string_filter_set_expression: - * @self: a `GtkStringFilter` - * @expression: (nullable): a `GtkExpression` + * @self: a string filter + * @expression: (nullable): the expression * * Sets the expression that the string filter uses to * obtain strings from items. * - * The expression must have a value type of %G_TYPE_STRING. + * The expression must have a value type of `G_TYPE_STRING`. */ void gtk_string_filter_set_expression (GtkStringFilter *self, @@ -427,11 +426,11 @@ /** * gtk_string_filter_get_ignore_case: - * @self: a `GtkStringFilter` + * @self: a string filter * * Returns whether the filter ignores case differences. * - * Returns: %TRUE if the filter ignores case + * Returns: true if the filter ignores case */ gboolean gtk_string_filter_get_ignore_case (GtkStringFilter *self) @@ -443,8 +442,8 @@ /** * gtk_string_filter_set_ignore_case: - * @self: a `GtkStringFilter` - * @ignore_case: %TRUE to ignore case + * @self: a string filter + * @ignore_case: true to ignore case * * Sets whether the filter ignores case differences. */ @@ -471,7 +470,7 @@ /** * gtk_string_filter_get_match_mode: - * @self: a `GtkStringFilter` + * @self: a string filter * * Returns the match mode that the filter is using. * @@ -487,7 +486,7 @@ /** * gtk_string_filter_set_match_mode: - * @self: a `GtkStringFilter` + * @self: a string filter * @mode: the new match mode * * Sets the match mode for the filter.
diff --git a/gtk/gtkstringfilter.h b/gtk/gtkstringfilter.h index 1ed070a..55119de 100644 --- a/gtk/gtkstringfilter.h +++ b/gtk/gtkstringfilter.h
@@ -31,11 +31,11 @@ /** * GtkStringFilterMatchMode: * @GTK_STRING_FILTER_MATCH_MODE_EXACT: The search string and - * text must match exactly. + * text must match exactly * @GTK_STRING_FILTER_MATCH_MODE_SUBSTRING: The search string - * must be contained as a substring inside the text. + * must be contained as a substring inside the text * @GTK_STRING_FILTER_MATCH_MODE_PREFIX: The text must begin - * with the search string. + * with the search string * * Specifies how search strings are matched inside text. */