[gtk+/gi-annotations: 3/17] Move documentation of GtkFileFilter inline

[Pavel Holejsovsky <pholejs src gnome org>]

commit 33377ea4bd2b485767c461d78c1ae1f124bd27c0
Author: Pavel Holejsovsky <pavel holejsovsky gmail com>
Date:   Thu Jan 13 15:31:34 2011 +0100

    Move documentation of GtkFileFilter inline

 docs/reference/gtk/tmpl/gtkfilefilter.sgml |  170 ----------------------------
 gtk/gtkfilefilter.c                        |   24 ++++
 gtk/gtkfilefilter.h                        |   35 ++++++
 3 files changed, 59 insertions(+), 170 deletions(-)
---
diff --git a/gtk/gtkfilefilter.c b/gtk/gtkfilefilter.c
index 04f3c55..cdfb6cb 100644
--- a/gtk/gtkfilefilter.c
+++ b/gtk/gtkfilefilter.c
@@ -18,6 +18,30 @@
  * Boston, MA 02111-1307, USA.
  */
 
+/**
+ * SECTION:gtkfilefilter
+ * @Short_description: A filter for selecting a file subset
+ * @Title: GtkFileFilter
+ *
+ * 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()).
+ *
+ * Filtering by mime types handles aliasing and subclassing of mime
+ * types; e.g. a filter for text/plain also matches a file with mime
+ * type application/rtf, since application/rtf is a subclass of
+ * 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().
+ *
+ * @see_also: #GtkFileChooser
+ */
+
 #include "config.h"
 #include <string.h>
 
diff --git a/gtk/gtkfilefilter.h b/gtk/gtkfilefilter.h
index 7a848e5..c566ef1 100644
--- a/gtk/gtkfilefilter.h
+++ b/gtk/gtkfilefilter.h
@@ -36,6 +36,17 @@ G_BEGIN_DECLS
 typedef struct _GtkFileFilter     GtkFileFilter;
 typedef struct _GtkFileFilterInfo GtkFileFilterInfo;
 
+/**
+ * GtkFileFilterFlags:
+ * @GTK_FILE_FILTER_FILENAME: the filename of the file being tested
+ * @GTK_FILE_FILTER_URI: the URI for the file being tested
+ * @GTK_FILE_FILTER_DISPLAY_NAME: the string that will be used to 
+ *   display the file in the file chooser
+ * @GTK_FILE_FILTER_MIME_TYPE: the mime type of the file
+ * 
+ * These flags indicate what parts of a #GtkFileFilterInfo struct
+ * are filled or need to be filled. 
+ */
 typedef enum {
   GTK_FILE_FILTER_FILENAME     = 1 << 0,
   GTK_FILE_FILTER_URI          = 1 << 1,
@@ -43,9 +54,33 @@ typedef enum {
   GTK_FILE_FILTER_MIME_TYPE    = 1 << 3
 } GtkFileFilterFlags;
 
+/**
+ * GtkFileFilterFunc:
+ * @filter_info: a #GtkFileFilterInfo that is filled according
+ *   to the @needed flags passed to gtk_file_filter_add_custom()
+ * @data: user data passed to gtk_file_filter_add_custom()
+ *
+ * The type of function that is used with custom filters, see
+ * gtk_file_filter_add_custom().
+ *
+ * @Returns: %TRUE if the file should be displayed
+ */
 typedef gboolean (*GtkFileFilterFunc) (const GtkFileFilterInfo *filter_info,
 				       gpointer                 data);
 
+/**
+ * GtkFileFilterInfo:
+ * @contains: Flags indicating which of the following fields need
+ *   are filled
+ * @filename: the filename of the file being tested
+ * @uri: the URI for the file being tested
+ * @display_name: the string that will be used to display the file
+ *   in the file chooser
+ * @mime_type: the mime type of the file
+ *
+ * A #GtkFileFilterInfo struct is used to pass information about the
+ * tested file to gtk_file_filter_filter().
+ */
 struct _GtkFileFilterInfo
 {
   GtkFileFilterFlags contains;