diff --git a/gtk/gtkentrycompletion.c b/gtk/gtkentrycompletion.c
index fb6e558817..b60942ac85 100644
--- a/gtk/gtkentrycompletion.c
+++ b/gtk/gtkentrycompletion.c
@@ -1343,6 +1343,9 @@ gtk_entry_completion_insert_action (GtkEntryCompletion *completion,
  * with text @text. If you want the action item to have markup, use
  * gtk_entry_completion_insert_action_markup().
  *
+ * Note that @index_ is a relative position in the list of actions and
+ * the position of an action can change when deleting a different action.
+ *
  * Since: 2.4
  */
 void
@@ -1385,6 +1388,9 @@ gtk_entry_completion_insert_action_markup (GtkEntryCompletion *completion,
  *
  * Deletes the action at @index_ from @completion’s action list.
  *
+ * Note that @index_ is a relative position and the position of an
+ * action may have changed since it was inserted.
+ *
  * Since: 2.4
  */
 void