- * equal to @data according to @cmp_func and @cmp_data. If more than one item
- * is equal, it is not guaranteed that it is the first which is returned.
- * In that case, you can use g_sequence_iter_next() and g_sequence_iter_prev()
- * to get others.
- *
- * Return value: an #GSequenceIter pointing to the position of the first item
- * found equal to @data according to @cmp_func and @cmp_data.
+ * equal to @data according to @cmp_func and @cmp_data. If more than one
+ * item is equal, it is not guaranteed that it is the first which is
+ * returned. In that case, you can use g_sequence_iter_next() and
+ * g_sequence_iter_prev() to get others.
+ *
+ * @cmp_func is called with two items of the @seq and @user_data.
+ * It should return 0 if the items are equal, a negative value if
+ * the first item comes before the second, and a positive value if
+ * 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.
+ *
+ * Returns: an #GSequenceIter pointing to the position of the
+ * first item found equal to @data according to @cmp_func and
+ * @cmp_data, or %NULL if no such item exists