From 8393c6d9beb041fc03ae22a1d72660d884d4c447 Mon Sep 17 00:00:00 2001
From: Daniel Boles <dboles.src@gmail.com>
Date: Wed, 12 Jun 2019 17:52:58 +0100
Subject: [PATCH 1/2] Overlay: Improve overly brief blurbs @ child props

Be a bit clearer about what :pass-through does, and point :index at the
corresponding reorder_overlay() method that explains what an index means
---
 gtk/gtkoverlay.c | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/gtk/gtkoverlay.c b/gtk/gtkoverlay.c
index 030fe614cd..b483d1f240 100644
--- a/gtk/gtkoverlay.c
+++ b/gtk/gtkoverlay.c
@@ -774,7 +774,8 @@ gtk_overlay_class_init (GtkOverlayClass *klass)
   /**
    * GtkOverlay:pass-through:
    *
-   * Pass through input, does not affect main child.
+   * Whether to pass input through the overlay child to the main child.
+   * (Of course, this has no effect when set on the main child itself.)
    *
    * Since: 3.18
    */
@@ -786,7 +787,8 @@ gtk_overlay_class_init (GtkOverlayClass *klass)
   /**
    * GtkOverlay:index:
    *
-   * The index of the overlay in the parent, -1 for the main child.
+   * The index of the overlay child in the parent (or -1 for the main child).
+   * See gtk_overlay_reorder_overlay().
    *
    * Since: 3.18
    */

From 321a21959e1af7a1c779a775f8587bb7b56c7bd3 Mon Sep 17 00:00:00 2001
From: Daniel Boles <dboles.src@gmail.com>
Date: Thu, 13 Jun 2019 18:25:07 +0100
Subject: [PATCH 2/2] 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);