Move documentation to inline comments: GtkTreeModelSort

3 files changed, 108 insertions, 222 deletions

diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index de00d196f8..8a3a384076 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -130,6 +130,7 @@ gtktooltip.sgml
 gtktreednd.sgml
 gtktreemodel.sgml
 gtktreemodelfilter.sgml
+gtktreemodelsort.sgml
 gtktreeselection.sgml
 gtktreesortable.sgml
 gtktreestore.sgml
diff --git a/docs/reference/gtk/tmpl/gtktreemodelsort.sgml b/docs/reference/gtk/tmpl/gtktreemodelsort.sgml
deleted file mode 100644
index 1582216b25..0000000000
--- a/docs/reference/gtk/tmpl/gtktreemodelsort.sgml
+++ /dev/null
@@ -1,222 +0,0 @@
-<!-- ##### SECTION Title ##### -->
-GtkTreeModelSort
-
-<!-- ##### SECTION Short_Description ##### -->
-A GtkTreeModel which makes an underlying tree model sortable
-
-<!-- ##### SECTION Long_Description ##### -->
-<para>
-The #GtkTreeModelSort is a model which implements the #GtkTreeSortable
-interface.  It does not hold any data itself, but rather is created with
-a child model and proxies its data.  It has identical column types to
-this child model, and the changes in the child are propagated.  The
-primary purpose of this model is to provide a way to sort a different
-model without modifying it. Note that the sort function used by
-#GtkTreeModelSort is not guaranteed to be stable.
-</para>
-<para>
-The use of this is best demonstrated through an example.  In the
-following sample code we create two #GtkTreeView widgets each with a
-view of the same data.  As the model is wrapped here by a
-#GtkTreeModelSort, the two #GtkTreeView<!-- -->s can each sort their
-view of the data without affecting the other.  By contrast, if we
-simply put the same model in each widget, then sorting the first would
-sort the second.
-</para>
-<para>
-<example>
-<title>Using a <structname>GtkTreeModelSort</structname></title>
-<programlisting>
-{
-  GtkTreeView *tree_view1;
-  GtkTreeView *tree_view2;
-  GtkTreeModel *sort_model1;
-  GtkTreeModel *sort_model2;
-  GtkTreeModel *child_model;
-
-  /* get the child model */
-  child_model = get_my_model ();
-
-  /* Create the first tree */
-  sort_model1 = gtk_tree_model_sort_new_with_model (child_model);
-  tree_view1 = gtk_tree_view_new_with_model (sort_model1);
-
-  /* Create the second tree */
-  sort_model2 = gtk_tree_model_sort_new_with_model (child_model);
-  tree_view2 = gtk_tree_view_new_with_model (sort_model2);
-
-  /* Now we can sort the two models independently */
-  gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1),
-                                        COLUMN_1, GTK_SORT_ASCENDING);
-  gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2),
-                                        COLUMN_1, GTK_SORT_DESCENDING);
-}
-</programlisting>
-</example>
-</para>
-
-<para>
-To demonstrate how to access the underlying child model from the sort
-model, the next example will be a callback for the #GtkTreeSelection
-"changed" signal.  In this callback, we get a string from COLUMN_1 of
-the model.  We then modify the string, find the same selected row on the
-child model, and change the row there.
-</para>
-
-<para>
-<example>
-<title>Accessing the child model of in a selection changed callback</title>
-<programlisting>
-void
-selection_changed (GtkTreeSelection *selection, gpointer data)
-{
-  GtkTreeModel *sort_model = NULL;
-  GtkTreeModel *child_model;
-  GtkTreeIter sort_iter;
-  GtkTreeIter child_iter;
-  char *some_data = NULL;
-  char *modified_data;
-
-  /* Get the current selected row and the model. */
-  if (! gtk_tree_selection_get_selected (selection,
-                                         &amp;sort_model,
-                                         &amp;sort_iter))
-    return;
-
-
-  /* Look up the current value on the selected row and get a new value
-   * to change it to.
-   */
-  gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &amp;sort_iter,
-                      COLUMN_1, &amp;some_data,
-                      -1);
-
-  modified_data = change_the_data (some_data);
-  g_free (some_data);
-
-  /* Get an iterator on the child model, instead of the sort model. */
-  gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model),
-                                                  &amp;child_iter,
-                                                  &amp;sort_iter);
-
-  /* Get the child model and change the value of the row.  In this
-   * example, the child model is a GtkListStore.  It could be any other
-   * type of model, though.
-   */
-  child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model));
-  gtk_list_store_set (GTK_LIST_STORE (child_model), &amp;child_iter,
-                      COLUMN_1, &amp;modified_data,
-                      -1);
-  g_free (modified_data);
-}
-</programlisting>
-</example>
-</para>
-
-<!-- ##### SECTION See_Also ##### -->
-<para>
-#GtkTreeModel, #GtkListStore, #GtkTreeStore, #GtkTreeSortable, #GtkTreeModelFilter
-</para>
-
-<!-- ##### SECTION Stability_Level ##### -->
-
-
-<!-- ##### SECTION Image ##### -->
-
-
-<!-- ##### STRUCT GtkTreeModelSort ##### -->
-<para>
-This should not be accessed directly.  Use the accessor functions below.
-</para>
-
-
-<!-- ##### ARG GtkTreeModelSort:model ##### -->
-<para>
-
-</para>
-
-<!-- ##### FUNCTION gtk_tree_model_sort_new_with_model ##### -->
-<para>
-
-</para>
-
-@child_model: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_tree_model_sort_get_model ##### -->
-<para>
-
-</para>
-
-@tree_model: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_tree_model_sort_convert_child_path_to_path ##### -->
-<para>
-
-</para>
-
-@tree_model_sort: 
-@child_path: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_tree_model_sort_convert_child_iter_to_iter ##### -->
-<para>
-
-</para>
-
-@tree_model_sort: 
-@sort_iter: 
-@child_iter: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_tree_model_sort_convert_path_to_child_path ##### -->
-<para>
-
-</para>
-
-@tree_model_sort: 
-@sorted_path: 
-@Returns: 
-
-
-<!-- ##### FUNCTION gtk_tree_model_sort_convert_iter_to_child_iter ##### -->
-<para>
-
-</para>
-
-@tree_model_sort: 
-@child_iter: 
-@sorted_iter: 
-
-
-<!-- ##### FUNCTION gtk_tree_model_sort_reset_default_sort_func ##### -->
-<para>
-
-</para>
-
-@tree_model_sort: 
-
-
-<!-- ##### FUNCTION gtk_tree_model_sort_clear_cache ##### -->
-<para>
-
-</para>
-
-@tree_model_sort: 
-
-
-<!-- ##### FUNCTION gtk_tree_model_sort_iter_is_valid ##### -->
-<para>
-
-</para>
-
-@tree_model_sort: 
-@iter: 
-@Returns: 
-
-
diff --git a/gtk/gtktreemodelsort.c b/gtk/gtktreemodelsort.c
index 1fc52266ed..9daa32fb48 100644
--- a/gtk/gtktreemodelsort.c
+++ b/gtk/gtktreemodelsort.c
@@ -49,6 +49,113 @@
 #include "gtktreednd.h"
 
 
+/**
+ * SECTION:gtktreemodelsort
+ * @Short_description: A GtkTreeModel which makes an underlying tree model sortable
+ * @Title: GtkTreeModelSort
+ * @See_also: #GtkTreeModel, #GtkListStore, #GtkTreeStore, #GtkTreeSortable, #GtkTreeModelFilter
+ *
+ * The #GtkTreeModelSort is a model which implements the #GtkTreeSortable
+ * interface.  It does not hold any data itself, but rather is created with
+ * a child model and proxies its data.  It has identical column types to
+ * this child model, and the changes in the child are propagated.  The
+ * primary purpose of this model is to provide a way to sort a different
+ * model without modifying it. Note that the sort function used by
+ * #GtkTreeModelSort is not guaranteed to be stable.
+ *
+ * The use of this is best demonstrated through an example.  In the
+ * following sample code we create two #GtkTreeView widgets each with a
+ * view of the same data.  As the model is wrapped here by a
+ * #GtkTreeModelSort, the two #GtkTreeView<!-- -->s can each sort their
+ * view of the data without affecting the other.  By contrast, if we
+ * simply put the same model in each widget, then sorting the first would
+ * sort the second.
+ *
+ * <example>
+ * <title>Using a <structname>GtkTreeModelSort</structname></title>
+ * <programlisting>
+ * {
+ *   GtkTreeView *tree_view1;
+ *   GtkTreeView *tree_view2;
+ *   GtkTreeModel *sort_model1;
+ *   GtkTreeModel *sort_model2;
+ *   GtkTreeModel *child_model;
+ *
+ *   // get the child model
+ *   child_model = get_my_model ();
+ *
+ *   // Create the first tree
+ *   sort_model1 = gtk_tree_model_sort_new_with_model (child_model);
+ *   tree_view1 = gtk_tree_view_new_with_model (sort_model1);
+ *
+ *   // Create the second tree
+ *   sort_model2 = gtk_tree_model_sort_new_with_model (child_model);
+ *   tree_view2 = gtk_tree_view_new_with_model (sort_model2);
+ *
+ *   // Now we can sort the two models independently
+ *   gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model1),
+ *                                         COLUMN_1, GTK_SORT_ASCENDING);
+ *   gtk_tree_sortable_set_sort_column_id (GTK_TREE_SORTABLE (sort_model2),
+ *                                         COLUMN_1, GTK_SORT_DESCENDING);
+ * }
+ * </programlisting>
+ * </example>
+ *
+ * To demonstrate how to access the underlying child model from the sort
+ * model, the next example will be a callback for the #GtkTreeSelection
+ * #GtkTreeSelection::changed signal.  In this callback, we get a string
+ * from COLUMN_1 of the model.  We then modify the string, find the same
+ * selected row on the child model, and change the row there.
+ *
+ * <example>
+ * <title>Accessing the child model of in a selection changed callback</title>
+ * <programlisting>
+ * void
+ * selection_changed (GtkTreeSelection *selection, gpointer data)
+ * {
+ *   GtkTreeModel *sort_model = NULL;
+ *   GtkTreeModel *child_model;
+ *   GtkTreeIter sort_iter;
+ *   GtkTreeIter child_iter;
+ *   char *some_data = NULL;
+ *   char *modified_data;
+ *
+ *   // Get the current selected row and the model.
+ *   if (! gtk_tree_selection_get_selected (selection,
+ *                                          &sort_model,
+ *                                          &sort_iter))
+ *     return;
+ *
+ *   /<!---->* Look up the current value on the selected row and get a new value
+ *    * to change it to.
+ *    *<!---->/
+ *   gtk_tree_model_get (GTK_TREE_MODEL (sort_model), &sort_iter,
+ *                       COLUMN_1, &some_data,
+ *                       -1);
+ *
+ *   modified_data = change_the_data (some_data);
+ *   g_free (some_data);
+ *
+ *   // Get an iterator on the child model, instead of the sort model.
+ *   gtk_tree_model_sort_convert_iter_to_child_iter (GTK_TREE_MODEL_SORT (sort_model),
+ *                                                   &child_iter,
+ *                                                   &sort_iter);
+ *
+ *   /<!---->* Get the child model and change the value of the row.  In this
+ *    * example, the child model is a GtkListStore.  It could be any other
+ *    * type of model, though.
+ *    *<!---->/
+ *   child_model = gtk_tree_model_sort_get_model (GTK_TREE_MODEL_SORT (sort_model));
+ *   gtk_list_store_set (GTK_LIST_STORE (child_model), &child_iter,
+ *                       COLUMN_1, &modified_data,
+ *                       -1);
+ *   g_free (modified_data);
+ * }
+ * </programlisting>
+ * </example>
+ */
+
+
 typedef struct _SortElt SortElt;
 typedef struct _SortLevel SortLevel;
 typedef struct _SortData SortData;