Make 3.0 parallel-installable to 2.x

[~andy/gtk] / docs / reference / gtk / tmpl / gtktreesortable.sgml

diff --git a/docs/reference/gtk/tmpl/gtktreesortable.sgml b/docs/reference/gtk/tmpl/gtktreesortable.sgml
index 1c9cf1e2ab91f9179e1f5472487290c62e5f0bc3..f5ebb8f6d80a53502ad53c146aa7ddfd7e9cc2f4 100644 (file)
--- a/docs/reference/gtk/tmpl/gtktreesortable.sgml
+++ b/docs/reference/gtk/tmpl/gtktreesortable.sgml
@@ -2,24 +2,39 @@
 GtkTreeSortable
 
 <!-- ##### SECTION Short_Description ##### -->
-
+The interface for sortable models used by GtkTreeView
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#GtkTreeSortable is an interface to be implemented by tree models which
+support sorting. The #GtkTreeView uses the methods provided by this interface
+to sort the model.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkTreeModel, #GtkTreeView
 </para>
 
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### STRUCT GtkTreeSortable ##### -->
 <para>
 
 </para>
 
 
+<!-- ##### SIGNAL GtkTreeSortable::sort-column-changed ##### -->
+<para>
+
+</para>
+
+@treesortable: the object which received the signal.
+
 <!-- ##### STRUCT GtkTreeSortableIface ##### -->
 <para>
 
@@ -35,14 +50,26 @@ GtkTreeSortable
 
 <!-- ##### USER_FUNCTION GtkTreeIterCompareFunc ##### -->
 <para>
-
+A GtkTreeIterCompareFunc should return a negative integer, zero, or a positive
+integer if @a sorts before @b, @a sorts with @b, or @a sorts after @b
+respectively. If two iters compare as equal, their order in the sorted model 
+is undefined. In order to ensure that the #GtkTreeSortable behaves as 
+expected, the GtkTreeIterCompareFunc must define a partial order on 
+the model, i.e. it must be reflexive, antisymmetric and transitive.
+</para>
+<para>
+For example, if @model is a product catalogue, then a compare function
+for the "price" column could be one which returns 
+<literal>price_of(@a) - price_of(@b)</literal>.
 </para>
 
-@model: 
-@a: 
-@b: 
-@user_data: 
-@Returns: 
+@model: The #GtkTreeModel the comparison is within
+@a: A #GtkTreeIter in @model
+@b: Another #GtkTreeIter in @model
+@user_data: Data passed when the compare func is assigned e.g. by
+gtk_tree_sortable_set_sort_func()
+@Returns: a negative integer, zero or a positive integer depending on whether
+    @a sorts before, with or after @b
 
 
 <!-- ##### FUNCTION gtk_tree_sortable_sort_column_changed ##### -->
@@ -106,10 +133,3 @@ GtkTreeSortable
 @Returns: 
 
 
-<!-- ##### SIGNAL GtkTreeSortable::sort-column-changed ##### -->
-<para>
-
-</para>
-
-@treesortable: the object which received the signal.
-