[glib] docs: GSequence: better document how to sort large amount of data

[Sébastien Wilmet <swilmet src gnome org>]

commit 3ee859d5fc9eb14910df7a84b8ce43a25ba6a632
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Fri Jan 5 15:13:44 2018 +0100

    docs: GSequence: better document how to sort large amount of data
    
    It was documented at strange places: in g_sequence_search*() and
    g_sequence_lookup*(), but how to insert and sort data is not done by
    those functions.
    
    So instead, add the information to the class description (since it
    involves several functions), and add also the information in
    g_sequence_insert_sorted() and g_sequence_insert_sorted_iter() as a kind
    of warning when using those functions.
    
    Note that before this commit, it was not explained *why* it is better to
    call g_sequence_sort() after doing a lot of unsorted insertions. Now it
    is documented as "more efficient" (I think it's the only reason that
    makes sense, otherwise why was it documented?).
    
    https://bugzilla.gnome.org/show_bug.cgi?id=792455

 glib/gsequence.c |   34 ++++++++++++++++++----------------
 1 files changed, 18 insertions(+), 16 deletions(-)
---
diff --git a/glib/gsequence.c b/glib/gsequence.c
index 6ef3f14..a59ff5b 100644
--- a/glib/gsequence.c
+++ b/glib/gsequence.c
@@ -61,6 +61,12 @@
  * g_sequence_move_range() will not invalidate the iterators pointing
  * to it. The only operation that will invalidate an iterator is when
  * the element it points to is removed from any sequence.
+ *
+ * To sort the data, either use g_sequence_insert_sorted() or
+ * g_sequence_insert_sorted_iter() to add data to the #GSequence or, if
+ * you want to add a large amount of data, it is more efficient to call
+ * g_sequence_sort() or g_sequence_sort_iter() after doing unsorted
+ * insertions.
  */
 
 /**
@@ -707,6 +713,10 @@ g_sequence_sort (GSequence        *seq,
  * if the first item comes before the second, and a positive value
  * if the second  item comes before the first.
  *
+ * Note that when adding a large amount of data to a #GSequence,
+ * it is more efficient to do unsorted insertions and then call
+ * g_sequence_sort() or g_sequence_sort_iter().
+ *
  * Returns: (transfer none): a #GSequenceIter pointing to the new item.
  *
  * Since: 2.14
@@ -788,10 +798,7 @@ g_sequence_sort_changed (GSequenceIter    *iter,
  * consider using g_sequence_lookup().
  *
  * This function will fail if the data contained in the sequence is
- * unsorted.  Use g_sequence_insert_sorted() or
- * g_sequence_insert_sorted_iter() to add data to your sequence or, if
- * you want to add a large amount of data, call g_sequence_sort() after
- * doing unsorted insertions.
+ * unsorted.
  *
  * Returns: (transfer none): an #GSequenceIter pointing to the position where @data
  *     would have been inserted according to @cmp_func and @cmp_data
@@ -835,10 +842,7 @@ g_sequence_search (GSequence        *seq,
  * the second item comes before the first.
  *
  * This function will fail if the data contained in the sequence is
- * unsorted.  Use g_sequence_insert_sorted() or
- * g_sequence_insert_sorted_iter() to add data to your sequence or, if
- * you want to add a large amount of data, call g_sequence_sort() after
- * doing unsorted insertions.
+ * unsorted.
  *
  * Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of the
  *     first item found equal to @data according to @cmp_func and
@@ -1002,6 +1006,10 @@ g_sequence_sort_changed_iter (GSequenceIter            *iter,
  * first iterator comes before the second, and a positive value
  * if the second iterator comes before the first.
  *
+ * Note that when adding a large amount of data to a #GSequence,
+ * it is more efficient to do unsorted insertions and then call
+ * g_sequence_sort() or g_sequence_sort_iter().
+ *
  * Returns: (transfer none): a #GSequenceIter pointing to the new item
  *
  * Since: 2.14
@@ -1068,10 +1076,7 @@ g_sequence_insert_sorted_iter (GSequence                *seq,
  * consider using g_sequence_lookup_iter().
  *
  * This function will fail if the data contained in the sequence is
- * unsorted.  Use g_sequence_insert_sorted() or
- * g_sequence_insert_sorted_iter() to add data to your sequence or, if
- * you want to add a large amount of data, call g_sequence_sort() after
- * doing unsorted insertions.
+ * unsorted.
  *
  * Returns: (transfer none): a #GSequenceIter pointing to the position in @seq
  *     where @data would have been inserted according to @iter_cmp
@@ -1126,10 +1131,7 @@ g_sequence_search_iter (GSequence                *seq,
  * value if the second iterator comes before the first.
  *
  * This function will fail if the data contained in the sequence is
- * unsorted.  Use g_sequence_insert_sorted() or
- * g_sequence_insert_sorted_iter() to add data to your sequence or, if
- * you want to add a large amount of data, call g_sequence_sort() after
- * doing unsorted insertions.
+ * unsorted.
  *
  * Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of
  *     the first item found equal to @data according to @cmp_func