diff --git a/gtk/gtkeditable.c b/gtk/gtkeditable.c
index 41fb0b729c..cf71f1c58e 100644
--- a/gtk/gtkeditable.c
+++ b/gtk/gtkeditable.c
@@ -1222,6 +1222,15 @@ gtk_editable_delegate_get_property (GObject    *object,
  * }
  * ```
  *
+ * Note that the widget which is the delegate *must* be a direct child of
+ * this widget, otherwise your implementation of [vfunc@Gtk.Accessible.get_platform_state]
+ * might not even be called, as the platform change will originate from
+ * the parent of the delegate, and, as a result, will not work properly.
+ *
+ * So, if you can't ensure the direct child condition, you should give the
+ * delegate the %GTK_ACCESSIBLE_ROLE_TEXT_BOX role, or you can
+ * change your tree to allow this function to work.
+ *
  * Since: 4.10
  */
 gboolean