gtktreemodelfilter: Move documentation to inline comments

2 files changed, 60 insertions, 0 deletions

diff --git a/gtk/gtktreemodelfilter.c b/gtk/gtktreemodelfilter.c
index 8699462648..d7a155ac9a 100644
--- a/gtk/gtktreemodelfilter.c
+++ b/gtk/gtktreemodelfilter.c
@@ -25,6 +25,37 @@
 #include "gtkprivate.h"
 #include <string.h>
 
+
+/**
+ * SECTION:gtktreemodelfilter
+ * @Short_description: A GtkTreeModel which hides parts of an underlying tree model
+ * @Title: GtkTreeModelFilter
+ * @See_also:#GtkTreeModelSort
+ *
+ * A #GtkTreeModelFilter is a tree model which wraps another tree model,
+ * and can do the following things:
+ * <itemizedlist>
+ * <listitem><para>
+ * Filter specific rows, based on data from a "visible column", a column
+ * storing booleans indicating whether the row should be filtered or not,
+ * or based on the return value of a "visible function", which gets a
+ * model, iter and user_data and returns a boolean indicating whether the
+ * row should be filtered or not.
+ * </para></listitem>
+ * <listitem><para>
+ * Modify the "appearance" of the model, using a modify function.
+ * This is extremely powerful and allows for just changing
+ * some values and also for creating a completely different model based on
+ * the given child model.
+ * </para></listitem>
+ * <listitem><para>
+ * Set a different root node, also known as a "virtual root". You can pass in
+ * a #GtkTreePath indicating the root node for the filter at construction time.
+ * </para></listitem>
+ * </itemizedlist>
+ */
+
+
 /* ITER FORMAT:
  *
  * iter->stamp = filter->priv->stamp
diff --git a/gtk/gtktreemodelfilter.h b/gtk/gtktreemodelfilter.h
index 67e34fbb89..1dc097a5d8 100644
--- a/gtk/gtktreemodelfilter.h
+++ b/gtk/gtktreemodelfilter.h
@@ -37,9 +37,38 @@ G_BEGIN_DECLS
 #define GTK_IS_TREE_MODEL_FILTER_CLASS(vtable)  (G_TYPE_CHECK_CLASS_TYPE ((vtable), GTK_TYPE_TREE_MODEL_FILTER))
 #define GTK_TREE_MODEL_FILTER_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), GTK_TYPE_TREE_MODEL_FILTER, GtkTreeModelFilterClass))
 
+/**
+ * GtkTreeModelFilterVisibleFunc:
+ * @model: the child model of the #GtkTreeModelFilter
+ * @iter: a #GtkTreeIter pointing to the row in @model whose visibility
+ *   is determined
+ * @data: user data given to gtk_tree_model_filter_set_visible_func()
+ *
+ * A function which decides whether the row indicated by @iter is visible.
+ *
+ * Returns: Whether the row indicated by @iter is visible.
+ */
 typedef gboolean (* GtkTreeModelFilterVisibleFunc) (GtkTreeModel *model,
                                                     GtkTreeIter  *iter,
                                                     gpointer      data);
+
+/**
+ * GtkTreeModelFilterModifyFunc:
+ * @model: the #GtkTreeModelFilter
+ * @iter: a #GtkTreeIter pointing to the row whose display values are determined
+ * @value: A #GValue which is already initialized for with the correct type for
+ *  the column @column.
+ * @column: the column whose display value is determined
+ * @data: user data given to gtk_tree_model_filter_set_modify_func()
+ *
+ * A function which calculates display values from raw values in the model.
+ * It must fill @value with the display value for the column @column in the
+ * row indicated by @iter.
+ *
+ * Since this function is called for each data access, it's not a
+ * particularly efficient operation.
+ */
+
 typedef void (* GtkTreeModelFilterModifyFunc) (GtkTreeModel *model,
                                                GtkTreeIter  *iter,
                                                GValue       *value,