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)

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:

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
+function (returns less than zero for first arg is less than second arg, 
-first arg is greater 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>
 

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
+comparison function (returns less than zero for first arg is less than second 
-equal, 1 if first arg is greater than second arg).
+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.

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
+function (returns less than zero for first arg is less than second arg, 
-first arg is greater 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, 
+The comparison function for g_ptr_array_sort() doesn't take the pointers 
-it takes pointers to the pointers in the array.
+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, 
+The comparison function for g_ptr_array_sort_with_data() doesn't take the 
-it takes pointers to the pointers in the array.
+pointers from the array as arguments, it takes pointers to the pointers in 
+the array.
 </para></note>
 
 @array: a #GPtrArray.