Enhance sort() documentation. (#314839, Behdad Esfahbod)

2005-08-30  Matthias Clasen  <mclasen@redhat.com>

	* glib/tmpl/arrays.sgml:
	* glib/tmpl/arrays_pointer.sgml:
	* glib/tmpl/arrays_byte.sgml: Enhance sort() documentation.
	(#314839, Behdad Esfahbod)

4 files changed, 36 insertions, 13 deletions

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index de6483aed..2d14ed2b3 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,10 @@
+2005-08-30  Matthias Clasen  <mclasen@redhat.com>
+
+	* glib/tmpl/arrays.sgml: 
+	* glib/tmpl/arrays_pointer.sgml: 
+	* glib/tmpl/arrays_byte.sgml: Enhance sort() documentation.
+	(#314839, Behdad Esfahbod)
+
 2005-08-26  Matthias Clasen  <mclasen@redhat.com>
 
 	* glib/glib-docs.sgml:
diff --git a/docs/reference/glib/tmpl/arrays.sgml b/docs/reference/glib/tmpl/arrays.sgml
index 4ed62071f..57b0e3680 100644
--- a/docs/reference/glib/tmpl/arrays.sgml
+++ b/docs/reference/glib/tmpl/arrays.sgml
@@ -231,8 +231,12 @@ Removes the given number of elements starting at the given index from a
 <!-- ##### FUNCTION g_array_sort ##### -->
 <para>
 Sorts a #GArray using @compare_func which should be a qsort()-style comparison
-function (returns -1 for first arg is less than second arg, 0 for equal, 1 if
-first arg is greater than second arg).
+function (returns less than zero for first arg is less than second arg, 
+zero for equal, greater zero if first arg is greater than second arg).
+</para>
+<para>
+If two array elements compare equal, their order in the sorted array is
+undefined.
 </para>
 
 @array: a #GArray.
@@ -241,7 +245,7 @@ first arg is greater than second arg).
 
 <!-- ##### FUNCTION g_array_sort_with_data ##### -->
 <para>
-Like g_array_sort(), but the comparison function receives a user data
+Like g_array_sort(), but the comparison function receives an extra user data
 argument.
 </para>
 
diff --git a/docs/reference/glib/tmpl/arrays_byte.sgml b/docs/reference/glib/tmpl/arrays_byte.sgml
index 39e24d353..7524853c4 100644
--- a/docs/reference/glib/tmpl/arrays_byte.sgml
+++ b/docs/reference/glib/tmpl/arrays_byte.sgml
@@ -144,8 +144,13 @@ Removes the given number of bytes starting at the given index from a
 <!-- ##### FUNCTION g_byte_array_sort ##### -->
 <para>
 Sorts a byte array, using @compare_func which should be a qsort()-style
-comparison function (returns -1 for first arg is less than second arg, 0 for
-equal, 1 if first arg is greater than second arg).
+comparison function (returns less than zero for first arg is less than second 
+arg, zero for equal, greater than zero if first arg is greater than second 
+arg).
+</para>
+<para>
+If two array elements compare equal, their order in the sorted array is
+undefined.
 </para>
 
 @array: a #GByteArray.
@@ -154,7 +159,8 @@ equal, 1 if first arg is greater than second arg).
 
 <!-- ##### FUNCTION g_byte_array_sort_with_data ##### -->
 <para>
-Like g_byte_array_sort(), but the comparison function takes a user data argument.
+Like g_byte_array_sort(), but the comparison function takes an extra user data
+argument.
 </para>
 
 @array: a #GByteArray.
diff --git a/docs/reference/glib/tmpl/arrays_pointer.sgml b/docs/reference/glib/tmpl/arrays_pointer.sgml
index 0c912d9fb..139c9cee4 100644
--- a/docs/reference/glib/tmpl/arrays_pointer.sgml
+++ b/docs/reference/glib/tmpl/arrays_pointer.sgml
@@ -173,12 +173,16 @@ Removes the given number of pointers starting at the given index from a
 <!-- ##### FUNCTION g_ptr_array_sort ##### -->
 <para>
 Sorts the array, using @compare_func which should be a qsort()-style comparison
-function (returns -1 for first arg is less than second arg, 0 for equal, 1 if
-first arg is greater than second arg).
+function (returns less than zero for first arg is less than second arg, 
+zero for equal, greater than zero if irst arg is greater than second arg).
+</para>
+<para>
+If two array elements compare equal, their order in the sorted array is
+undefined.
 </para>
 <note><para>
-The comparison function for g_ptr_array_sort() doesn't take the pointers from the array as arguments, 
-it takes pointers to the pointers in the array.
+The comparison function for g_ptr_array_sort() doesn't take the pointers 
+from the array as arguments, it takes pointers to the pointers in the array.
 </para></note>
 
 @array: a #GPtrArray.
@@ -187,11 +191,13 @@ it takes pointers to the pointers in the array.
 
 <!-- ##### FUNCTION g_ptr_array_sort_with_data ##### -->
 <para>
-Like g_ptr_array_sort(), but the comparison function has a user data argument.
+Like g_ptr_array_sort(), but the comparison function has an extra user data 
+argument.
 </para>
 <note><para>
-The comparison function for g_ptr_array_sort_with_data() doesn't take the pointers from the array as arguments, 
-it takes pointers to the pointers in the array.
+The comparison function for g_ptr_array_sort_with_data() doesn't take the 
+pointers from the array as arguments, it takes pointers to the pointers in 
+the array.
 </para></note>
 
 @array: a #GPtrArray.