[gtk/file-filter2: 7/7] docs: Cleanups for the file filter docs

[Matthias Clasen <matthiasc src gnome org>]

commit 661d784c7bcbe21ac8578f181e1b2882c7140b9e
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Jul 4 10:24:09 2020 -0400

    docs: Cleanups for the file filter docs
    
    Now that GtkFileFilter is a GtkFilter, move it to the
    filter section of the docs. While we are at it, touch
    up the docs in some places.

 docs/reference/gtk/gtk4-docs.xml |  4 ++--
 gtk/gtkfilefilter.c              | 49 ++++++++++++++++++++++------------------
 2 files changed, 29 insertions(+), 24 deletions(-)
---
diff --git a/docs/reference/gtk/gtk4-docs.xml b/docs/reference/gtk/gtk4-docs.xml
index 643fc0ebc1..3e2751c6b7 100644
--- a/docs/reference/gtk/gtk4-docs.xml
+++ b/docs/reference/gtk/gtk4-docs.xml
@@ -54,8 +54,9 @@
       <section>
         <xi:include href="xml/gtkfilter.xml" />
         <xi:include href="xml/gtkcustomfilter.xml" />
-        <xi:include href="xml/gtkstringfilter.xml" />
         <xi:include href="xml/gtkmultifilter.xml" />
+        <xi:include href="xml/gtkstringfilter.xml" />
+        <xi:include href="xml/gtkfilefilter.xml" />
       </section>
       <xi:include href="xml/gtkflattenlistmodel.xml" />
       <xi:include href="xml/gtkmaplistmodel.xml" />
@@ -285,7 +286,6 @@
       <xi:include href="xml/gtkfilechoosernative.xml" />
       <xi:include href="xml/gtkfilechooserdialog.xml" />
       <xi:include href="xml/gtkfilechooserwidget.xml" />
-      <xi:include href="xml/gtkfilefilter.xml" />
       <xi:include href="xml/gtkfontchooser.xml" />
       <xi:include href="xml/gtkfontbutton.xml" />
       <xi:include href="xml/gtkfontchooserwidget.xml" />
diff --git a/gtk/gtkfilefilter.c b/gtk/gtkfilefilter.c
index 786291ac67..1f0f88860b 100644
--- a/gtk/gtkfilefilter.c
+++ b/gtk/gtkfilefilter.c
@@ -18,15 +18,14 @@
 
 /**
  * SECTION:gtkfilefilter
- * @Short_description: A filter for selecting a file subset
+ * @Short_description: Filtering files
  * @Title: GtkFileFilter
  * @see_also: #GtkFileChooser
  *
  * A GtkFileFilter can be used to restrict the files being shown in a
  * #GtkFileChooser. Files can be filtered based on their name (with
- * gtk_file_filter_add_pattern()), on their mime type (with
- * gtk_file_filter_add_mime_type()), or by a custom filter function
- * (with gtk_file_filter_add_custom()).
+ * gtk_file_filter_add_pattern()) or on their mime type (with
+ * gtk_file_filter_add_mime_type()).
  *
  * Filtering by mime types handles aliasing and subclassing of mime
  * types; e.g. a filter for text/plain also matches a file with mime
@@ -34,9 +33,10 @@
  * text/plain. Note that #GtkFileFilter allows wildcards for the
  * subtype of a mime type, so you can e.g. filter for image/\*.
  *
- * Normally, filters are used by adding them to a #GtkFileChooser,
- * see gtk_file_chooser_add_filter(), but it is also possible
- * to manually use a filter on a file with gtk_file_filter_filter().
+ * Normally, file filters are used by adding them to a #GtkFileChooser
+ * (see gtk_file_chooser_add_filter()), but it is also possible to
+ * manually use a file filter on any #GtkFilterListModel containing
+ * #GFileInfo objects.
  *
  * # GtkFileFilter as GtkBuildable
  *
@@ -438,18 +438,20 @@ gtk_file_filter_buildable_custom_tag_end (GtkBuildable *buildable,
 
 /**
  * gtk_file_filter_new:
- * 
+ *
  * Creates a new #GtkFileFilter with no rules added to it.
+ *
  * Such a filter doesn’t accept any files, so is not
  * particularly useful until you add rules with
  * gtk_file_filter_add_mime_type(), gtk_file_filter_add_pattern(),
- * or gtk_file_filter_add_custom(). To create a filter
- * that accepts any file, use:
+ * or gtk_file_filter_add_pixbuf_formats().
+ *
+ * To create a filter that accepts any file, use:
  * |[<!-- language="C" -->
  * GtkFileFilter *filter = gtk_file_filter_new ();
  * gtk_file_filter_add_pattern (filter, "*");
  * ]|
- * 
+ *
  * Returns: a new #GtkFileFilter
  **/
 GtkFileFilter *
@@ -463,14 +465,14 @@ gtk_file_filter_new (void)
  * @filter: a #GtkFileFilter
  * @name: (allow-none): the human-readable-name for the filter, or %NULL
  *   to remove any existing name.
- * 
- * Sets the human-readable name of the filter; this is the string
- * that will be displayed in the file selector user interface if
- * there is a selectable list of filters.
+ *
+ * Sets a human-readable name of the filter; this is the string
+ * that will be displayed in the file chooser if there is a selectable
+ * list of filters.
  **/
 void
 gtk_file_filter_set_name (GtkFileFilter *filter,
-                         const gchar   *name)
+                          const gchar   *name)
 {
   g_return_if_fail (GTK_IS_FILE_FILTER (filter));
 
@@ -486,18 +488,18 @@ gtk_file_filter_set_name (GtkFileFilter *filter,
 /**
  * gtk_file_filter_get_name:
  * @filter: a #GtkFileFilter
- * 
+ *
  * Gets the human-readable name for the filter. See gtk_file_filter_set_name().
- * 
+ *
  * Returns: (nullable): The human-readable name of the filter,
- *   or %NULL. This value is owned by GTK+ and must not
+ *   or %NULL. This value is owned by GTK and must not
  *   be modified or freed.
  **/
 const gchar *
 gtk_file_filter_get_name (GtkFileFilter *filter)
 {
   g_return_val_if_fail (GTK_IS_FILE_FILTER (filter), NULL);
-  
+
   return filter->name;
 }
 
@@ -531,7 +533,7 @@ file_filter_add_attribute (GtkFileFilter *filter,
  * gtk_file_filter_add_mime_type:
  * @filter: A #GtkFileFilter
  * @mime_type: name of a MIME type
- * 
+ *
  * Adds a rule allowing a given mime type to @filter.
  **/
 void
@@ -578,9 +580,12 @@ gtk_file_filter_add_pattern (GtkFileFilter *filter,
 /**
  * gtk_file_filter_add_pixbuf_formats:
  * @filter: a #GtkFileFilter
- * 
+ *
  * Adds a rule allowing image files in the formats supported
  * by GdkPixbuf.
+ *
+ * This is equivalent to calling gtk_file_filter_add_mime_type()
+ * for all the supported mime types.
  **/
 void
 gtk_file_filter_add_pixbuf_formats (GtkFileFilter *filter)