Created attachment 366717 [details] [review]
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?).

Review of attachment 366717 [details] [review]:

::: glib/gsequence.c
@@ +716,3 @@
+ * Note that when adding a large amount of data to a #GSequence,
+ * it is more efficient to do unsorted insertions and then
+ * calling g_sequence_sort() or g_sequence_sort_iter().

Nitpick: s/calling/call/

@@ +1009,3 @@
+ * Note that when adding a large amount of data to a #GSequence,
+ * it is more efficient to do unsorted insertions and then
+ * calling g_sequence_sort() or g_sequence_sort_iter().

Nitpick: s/calling/call/

Created attachment 366859 [details] [review]
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?).

Review of attachment 366859 [details] [review]:

Thanks

Thanks for the review!

Attachment 366859 [details] pushed as 3ee859d - docs: GSequence: better document how to sort large amount of data