diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 317b45b3c2..05ea17bc9e 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -8689,7 +8689,9 @@ reset_style_recurse (GtkWidget *widget, gpointer data)
  * @widget: a #GtkWidget
  *
  * Updates the style context of @widget and all descendents
- * by updating its widget path.
+ * by updating its widget path. #GtkContainer<!-- -->s may want
+ * to use this on a child when reordering it in a way that a different
+ * style might apply to it. See also gtk_container_get_path_for_child().
  *
  * Since: 3.0
  */