[glib] gsequence: Various minor typo and reference fixes to the documentation

[Philip Withnall <pwithnall src gnome org>]

commit a8b4d516aa8f15eeb6e4c65fc0f908266f09f768
Author: Philip Withnall <withnall endlessm com>
Date:   Thu Apr 26 11:34:15 2018 +0100

    gsequence: Various minor typo and reference fixes to the documentation
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    Reviewed-by: nobody

 glib/gsequence.c | 38 ++++++++++++++++----------------------
 1 file changed, 16 insertions(+), 22 deletions(-)
---
diff --git a/glib/gsequence.c b/glib/gsequence.c
index a59ff5bf2..fd5464f06 100644
--- a/glib/gsequence.c
+++ b/glib/gsequence.c
@@ -588,13 +588,13 @@ g_sequence_remove_range (GSequenceIter *begin,
  * @begin: a #GSequenceIter
  * @end: a #GSequenceIter
  *
- * Inserts the (@begin, @end) range at the destination pointed to by ptr.
+ * Inserts the (@begin, @end) range at the destination pointed to by @dest.
  * The @begin and @end iters must point into the same sequence. It is
  * allowed for @dest to point to a different sequence than the one pointed
  * into by @begin and @end.
  *
- * If @dest is NULL, the range indicated by @begin and @end is
- * removed from the sequence. If @dest iter points to a place within
+ * If @dest is %NULL, the range indicated by @begin and @end is
+ * removed from the sequence. If @dest points to a place within
  * the (@begin, @end) range, the range does not move.
  *
  * Since: 2.14
@@ -704,14 +704,14 @@ g_sequence_sort (GSequence        *seq,
  * @cmp_func: the function used to compare items in the sequence
  * @cmp_data: user data passed to @cmp_func.
  *
- * Inserts @data into @sequence using @func to determine the new
+ * Inserts @data into @seq using @cmp_func to determine the new
  * position. The sequence must already be sorted according to @cmp_func;
  * otherwise the new position of @data is undefined.
  *
- * @cmp_func is called with two items of the @seq and @user_data.
+ * @cmp_func is called with two items of the @seq, and @cmp_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.
+ * 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
@@ -746,12 +746,13 @@ g_sequence_insert_sorted (GSequence        *seq,
  * @cmp_func: the function used to compare items in the sequence
  * @cmp_data: user data passed to @cmp_func.
  *
- * Moves the data pointed to a new position as indicated by @cmp_func. This
+ * Moves the data pointed to by @iter to a new position as indicated by
+ * @cmp_func. This
  * function should be called for items in a sequence already sorted according
  * to @cmp_func whenever some aspect of an item changes so that @cmp_func
  * may return different values for that item.
  *
- * @cmp_func is called with two items of the @seq and @user_data.
+ * @cmp_func is called with two items of the @seq, and @cmp_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.
@@ -789,7 +790,7 @@ g_sequence_sort_changed (GSequenceIter    *iter,
  * Returns an iterator pointing to the position where @data would
  * be inserted according to @cmp_func and @cmp_data.
  *
- * @cmp_func is called with two items of the @seq and @user_data.
+ * @cmp_func is called with two items of the @seq, and @cmp_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.
@@ -836,7 +837,7 @@ g_sequence_search (GSequence        *seq,
  * 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.
+ * @cmp_func is called with two items of the @seq, and @cmp_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.
@@ -875,7 +876,7 @@ g_sequence_lookup (GSequence        *seq,
  * @cmp_data: user data passed to @cmp_func
  *
  * Like g_sequence_sort(), but uses a #GSequenceIterCompareFunc instead
- * of a GCompareDataFunc as the compare function
+ * of a #GCompareDataFunc as the compare function
  *
  * @cmp_func is called with two iterators pointing into @seq. It should
  * return 0 if the iterators are equal, a negative value if the first
@@ -932,7 +933,8 @@ g_sequence_sort_iter (GSequence                *seq,
  * a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
  * the compare function.
  *
- * @iter_cmp is called with two iterators pointing into @seq. It should
+ * @iter_cmp is called with two iterators pointing into the #GSequence that
+ * @iter points into. It should
  * return 0 if the iterators are equal, a negative value if the first
  * iterator comes before the second, and a positive value if the second
  * iterator comes before the first.
@@ -990,7 +992,7 @@ g_sequence_sort_changed_iter (GSequenceIter            *iter,
  * @seq: a #GSequence
  * @data: data for the new item
  * @iter_cmp: the function used to compare iterators in the sequence
- * @cmp_data: user data passed to @cmp_func
+ * @cmp_data: user data passed to @iter_cmp
  *
  * Like g_sequence_insert_sorted(), but uses
  * a #GSequenceIterCompareFunc instead of a #GCompareDataFunc as
@@ -1001,11 +1003,6 @@ g_sequence_sort_changed_iter (GSequenceIter            *iter,
  * value if the first iterator comes before the second, and a
  * positive value if the second iterator comes before the first.
  *
- * It is called with two iterators pointing into @seq. It should
- * return 0 if the iterators are equal, a negative value if the
- * 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().
@@ -1134,7 +1131,7 @@ g_sequence_search_iter (GSequence                *seq,
  * unsorted.
  *
  * Returns: (transfer none) (nullable): an #GSequenceIter pointing to the position of
- *     the first item found equal to @data according to @cmp_func
+ *     the first item found equal to @data according to @iter_cmp
  *     and @cmp_data, or %NULL if no such item exists
  *
  * Since: 2.28
@@ -1337,9 +1334,6 @@ clamp_position (GSequence *seq,
   return pos;
 }
 
-/*
- * if pos > number of items or -1, will return end pointer
- */
 /**
  * g_sequence_get_iter_at_pos:
  * @seq: a #GSequence