[gtk/wip/dboles/overlay-docs-3: 42/42] Overlay: Use @index_, not @position, in reorder()

[Daniel Boles <dboles src gnome org>]

commit 321a21959e1af7a1c779a775f8587bb7b56c7bd3
Author: Daniel Boles <dboles src gmail com>
Date:   Thu Jun 13 18:25:07 2019 +0100

    Overlay: Use @index_, not @position, in reorder()
    
    We named the argument `position` in the code and doc arguments, but the
    rest of the documentation referred to `index` instead. That was maybe
    meant to hint at the child property named :index, but we can simply be
    fully clear here. We can call the argument `index_`, replacing the local
    variable with that name, thus avoiding any possible confusion with the
    unrelated ::get-child-position, and refer users to :index for completion
    
    `index_` is used instead of plain `index` in case anyone is #including
    <strings.h> and getting the old index() function superseded by strchr();
    see https://gitlab.gnome.org/GNOME/gtk/merge_requests/932#note_531149

 gtk/gtkoverlay.c | 12 ++++++------
 gtk/gtkoverlay.h |  6 +++---
 2 files changed, 9 insertions(+), 9 deletions(-)
---
diff --git a/gtk/gtkoverlay.c b/gtk/gtkoverlay.c
index b483d1f240..8dcaaf0ab7 100644
--- a/gtk/gtkoverlay.c
+++ b/gtk/gtkoverlay.c
@@ -534,13 +534,13 @@ gtk_overlay_remove (GtkContainer *container,
  * gtk_overlay_reorder_overlay:
  * @overlay: a #GtkOverlay
  * @child: the overlaid #GtkWidget to move
- * @position: the new index for @child in the list of overlay children
+ * @index_: the new index for @child in the list of overlay children
  *   of @overlay, starting from 0. If negative, indicates the end of
  *   the list
  *
  * Moves @child to a new @index in the list of @overlay children.
  * The list contains overlays in the order that these were
- * added to @overlay.
+ * added to @overlay by default. See also #GtkOverlay:index.
  *
  * A widget’s index in the @overlay children list determines which order
  * the children are drawn if they overlap. The first child is drawn at
@@ -551,7 +551,7 @@ gtk_overlay_remove (GtkContainer *container,
 void
 gtk_overlay_reorder_overlay (GtkOverlay *overlay,
                              GtkWidget  *child,
-                             gint        position)
+                             int         index_)
 {
   GtkOverlayPrivate *priv;
   GSList *old_link;
@@ -580,15 +580,15 @@ gtk_overlay_reorder_overlay (GtkOverlay *overlay,
 
   g_return_if_fail (old_link != NULL);
 
-  if (position < 0)
+  if (index_ < 0)
     {
       new_link = NULL;
       index = g_slist_length (priv->children) - 1;
     }
   else
     {
-      new_link = g_slist_nth (priv->children, position);
-      index = MIN (position, g_slist_length (priv->children) - 1);
+      new_link = g_slist_nth (priv->children, index_);
+      index = MIN (index_, g_slist_length (priv->children) - 1);
     }
 
   if (index == old_index)
diff --git a/gtk/gtkoverlay.h b/gtk/gtkoverlay.h
index bf9fc62761..cd94869ce9 100644
--- a/gtk/gtkoverlay.h
+++ b/gtk/gtkoverlay.h
@@ -84,9 +84,9 @@ GDK_AVAILABLE_IN_3_2
 void       gtk_overlay_add_overlay (GtkOverlay *overlay,
                                     GtkWidget  *widget);
 GDK_AVAILABLE_IN_3_18
-void       gtk_overlay_reorder_overlay (GtkOverlay     *overlay,
-                                       GtkWidget      *child,
-                                       gint            position);
+void       gtk_overlay_reorder_overlay (GtkOverlay *overlay,
+                                        GtkWidget  *child,
+                                        int         index_);
 GDK_AVAILABLE_IN_3_18
 gboolean   gtk_overlay_get_overlay_pass_through (GtkOverlay *overlay,
                                                 GtkWidget  *widget);