[gtk/ebassi/gidocgen: 226/471] filter: Add sections for AnyFilter and EveryFilter

[Emmanuele Bassi <ebassi src gnome org>]

commit c263ac1cbc7cfc2d6f5864503b05cad7b0a965e4
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Feb 27 10:52:22 2021 -0500

    filter: Add sections for AnyFilter and EveryFilter

 gtk/gtkfilter.c      | 34 +++++++++++++++++-----------------
 gtk/gtkfilter.h      |  5 -----
 gtk/gtkmultifilter.c | 52 +++++++++++++++++++++++++++++-----------------------
 3 files changed, 46 insertions(+), 45 deletions(-)
---
diff --git a/gtk/gtkfilter.c b/gtk/gtkfilter.c
index 2d76f8ff1c..27c4d1bfe7 100644
--- a/gtk/gtkfilter.c
+++ b/gtk/gtkfilter.c
@@ -25,22 +25,19 @@
 #include "gtktypebuiltins.h"
 
 /**
- * SECTION:gtkfilter
- * @Title: GtkFilter
- * @Short_description: Filtering items
- * @See_also: #GtkFilterListModel
+ * GtkFilter:
  *
- * A #GtkFilter object describes the filtering to be performed by a
- * #GtkFilterListModel.
+ * 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.
+ * or not by calling [method@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 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().
+ * case, they will emit the [signal@Gtk.Filter::changed] signal to notify
+ * that previous filter results are no longer valid and that items should
+ * be checked again via [method@Gtk.Filter.match].
  *
  * GTK provides various pre-made filter implementations for common filtering
  * operations. These filters often include properties that can be linked to
@@ -87,13 +84,16 @@ gtk_filter_class_init (GtkFilterClass *class)
    * @self: The #GtkFilter
    * @change: how the filter changed
    *
-   * This signal is emitted whenever the filter changed. Users of the filter
-   * should then check items again via gtk_filter_match().
+   * Emitted whenever the filter changed.
    *
-   * #GtkFilterListModel handles this signal automatically.
+   * Users of the filter should then check items again via
+   * [method@Gtk.Filter.match].
    *
-   * Depending on the @change parameter, not all items need to be changed, but
-   * only some. Refer to the #GtkFilterChange documentation for details.
+   * `GtkFilterListModel` handles this signal automatically.
+   *
+   * Depending on the @change parameter, not all items need
+   * to be checked, but only some. Refer to the [enum@Gtk.FilterChange]
+   * documentation for details.
    */
   signals[CHANGED] =
     g_signal_new (I_("changed"),
@@ -116,7 +116,7 @@ gtk_filter_init (GtkFilter *self)
 
 /**
  * gtk_filter_match:
- * @self: a #GtkFilter
+ * @self: a `GtkFilter`
  * @item: (type GObject) (transfer none): The item to check
  *
  * Checks if the given @item is matched by the filter or not.
diff --git a/gtk/gtkfilter.h b/gtk/gtkfilter.h
index 8fe080634f..a370f20e3e 100644
--- a/gtk/gtkfilter.h
+++ b/gtk/gtkfilter.h
@@ -75,11 +75,6 @@ typedef enum {
 
 #define GTK_TYPE_FILTER             (gtk_filter_get_type ())
 
-/**
- * GtkFilter:
- *
- * The object describing a filter.
- */
 GDK_AVAILABLE_IN_ALL
 G_DECLARE_DERIVABLE_TYPE (GtkFilter, gtk_filter, GTK, FILTER, GObject)
 
diff --git a/gtk/gtkmultifilter.c b/gtk/gtkmultifilter.c
index 3550d90c58..1d68c0bce1 100644
--- a/gtk/gtkmultifilter.c
+++ b/gtk/gtkmultifilter.c
@@ -35,19 +35,24 @@
 /*** MULTI FILTER ***/
 
 /**
- * SECTION:gtkmultifilter
- * @Title: GtkMultiFilter
- * @Short_description: Combining multiple filters
+ * GtkMultiFilter:
  *
- * GtkMultiFilter is the base type that implements support for handling
+ * `GtkMultiFilter` is the base type that implements support for handling
  * multiple filters.
+ */
+
+/**
+ * GtkAnyFilter:
  *
- * GtkAnyFilter is a subclass of GtkMultiFilter that matches an item
- * when at least one of its filters matches.
+ * `GtkAnyFilter` matches an item when at least one of its filters matches.
+ */
+
+/**
+ * GtkEveryFilter:
  *
- * GtkEveryFilter is a subclass of GtkMultiFilter that matches an item
- * when each of its filters matches.
+ * `GtkEveryFilter` matches an item when each of its filters matches.
  */
+
 struct _GtkMultiFilter
 {
   GtkFilter parent_instance;
@@ -164,11 +169,11 @@ gtk_multi_filter_init (GtkMultiFilter *self)
 
 /**
  * gtk_multi_filter_append:
- * @self: a #GtkMultiFilter
+ * @self: a `GtkMultiFilter`
  * @filter: (transfer full): A new filter to use
  *
  * Adds a @filter to @self to use for matching.
- **/
+ */
 void
 gtk_multi_filter_append (GtkMultiFilter *self,
                          GtkFilter    *filter)
@@ -185,11 +190,12 @@ gtk_multi_filter_append (GtkMultiFilter *self,
 
 /**
  * gtk_multi_filter_remove:
- * @self: a #GtkMultiFilter
+ * @self: a `GtkMultiFilter`
  * @position: position of filter to remove
  *
  * Removes the filter at the given @position from the list of filters used
  * by @self.
+ *
  * If @position is larger than the number of filters, nothing happens and
  * the function returns.
  **/
@@ -295,15 +301,15 @@ gtk_any_filter_init (GtkAnyFilter *self)
  * gtk_any_filter_new:
  *
  * Creates a new empty "any" filter.
- * Use gtk_multi_filter_append() to add filters to it.
+ *
+ * Use [method@Gtk.MultiFilter.append] to add filters to it.
  *
  * This filter matches an item if any of the filters added to it
- * matches the item.
- * In particular, this means that if no filter has been added to
- * it, the filter matches no item.
+ * matches the item. In particular, this means that if no filter
+ * has been added to it, the filter matches no item.
  *
- * Returns: a new #GtkAnyFilter
- **/
+ * Returns: a new `GtkAnyFilter`
+ */
 GtkAnyFilter *
 gtk_any_filter_new (void)
 {
@@ -393,15 +399,15 @@ gtk_every_filter_init (GtkEveryFilter *self)
  * gtk_every_filter_new:
  *
  * Creates a new empty "every" filter.
- * Use gtk_multi_filter_append() to add filters to it.
+ *
+ * Use [method@Gtk.MultiFilter.append] to add filters to it.
  *
  * This filter matches an item if each of the filters added to it
- * matches the item.
- * In particular, this means that if no filter has been added to
- * it, the filter matches every item.
+ * matches the item. In particular, this means that if no filter
+ * has been added to it, the filter matches every item.
  *
- * Returns: a new #GtkEveryFilter
- **/
+ * Returns: a new `GtkEveryFilter`
+ */
 GtkEveryFilter *
 gtk_every_filter_new (void)
 {