+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:
<!-- ##### 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.
<!-- ##### 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>
<!-- ##### 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.
<!-- ##### 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.
<!-- ##### 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.
<!-- ##### 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.