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

[Matthias Clasen <matthiasc src gnome org>]

commit da586803f873a4b2565840f8412b5b8aded0dfb7
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              | 55 +++++++++++++++++++++++-----------------
 2 files changed, 34 insertions(+), 25 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 3b73316e52..3017b15c4e 100644
--- a/gtk/gtkfilefilter.c
+++ b/gtk/gtkfilefilter.c
@@ -18,7 +18,7 @@
 
 /**
  * SECTION:gtkfilefilter
- * @Short_description: A filter for selecting a file subset
+ * @Short_description: Filtering files
  * @Title: GtkFileFilter
  * @see_also: #GtkFileChooser
  *
@@ -34,9 +34,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
  *
@@ -448,18 +449,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_custom().
+ *
+ * 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 *
@@ -473,14 +476,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));
 
@@ -496,18 +499,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;
 }
 
@@ -525,7 +528,7 @@ file_filter_add_rule (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
@@ -572,9 +575,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)
@@ -600,12 +606,15 @@ gtk_file_filter_add_pixbuf_formats (GtkFileFilter *filter)
  *   the file will be displayed.
  * @data: data to pass to @func
  * @notify: function to call to free @data when it is no longer needed.
- * 
+ *
  * Adds rule to a filter that allows files based on a custom callback
- * function. The bitfield @needed which is passed in provides information
+ * function.
+ *
+ * The bitfield @needed which is passed in provides information
  * about what sorts of information that the filter function needs;
- * this allows GTK+ to avoid retrieving expensive information when
- * it isn’t needed by the filter.
+ * this allows GTK to retrieve the needed information in advance, and
+ * to avoid retrieving expensive information when it isn’t needed by
+ * the filter.
  **/
 void
 gtk_file_filter_add_custom (GtkFileFilter         *filter,