diff --git a/docs/reference/gtk/migrating-3to4.md b/docs/reference/gtk/migrating-3to4.md
index 1762acdd53..ab51b791d5 100644
--- a/docs/reference/gtk/migrating-3to4.md
+++ b/docs/reference/gtk/migrating-3to4.md
@@ -523,6 +523,25 @@ option. You should always review the resulting changes.
 The <requires> tag now supports for the 'lib' attribute the
 'gtk' value only, instead of the 'gtk+' one previously.
 
+## Adapt to GtkBuilder API changes
+
+gtk_builder_connect_signals() no longer exists. Instead, signals are
+always connected automatically. If you need to add user data to your
+signals, gtk_builder_set_current_object() must be called. An important
+caveat is that you have to do this before loading any XML. This means if
+you need to use gtk_builder_set_current_object(), you can no longer use
+gtk_builder_new_from_file(), gtk_builder_new_from_resource(), or
+gtk_builder_new_from_string(). Instead, you must use vanilla gtk_builder_new(),
+then call gtk_builder_set_current_object(), then load the XML using
+gtk_builder_add_from_file(), gtk_builder_add_from_resource(), or
+gtk_builder_add_from_string(). You must check the return value for
+failure and manually abort with g_error() if something went wrong.
+
+You only have to worry about this if you were previously using
+gtk_builder_connect_signals(). If you are using templates, then
+gtk_widget_init_template() will call gtk_builder_set_current_object()
+for you, so templates work like before.
+
 ### Adapt to event controller API changes
 
 A few changes to the event controller and #GtkGesture APIs
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index ef1237fccc..d3edc4d0da 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -1153,9 +1153,6 @@ gtk_builder_create_bindings (GtkBuilder  *builder,
  * or gtk_builder_add_from_string() in order to merge multiple UI
  * descriptions into a single builder.
  *
- * Most users will probably want to use gtk_builder_new_from_file(),
- * gtk_builder_new_from_resource() or gtk_builder_new_from_string().
- *
  * Returns: a new (empty) #GtkBuilder object
  **/
 GtkBuilder *
@@ -1173,7 +1170,9 @@ gtk_builder_new (void)
  * Parses a file containing a [GtkBuilder UI definition][BUILDER-UI]
  * and merges it with the current contents of @builder.
  *
- * Most users will probably want to use gtk_builder_new_from_file().
+ * This function is useful if you need to call gtk_builder_set_current_object()
+ * to add user data to callbacks before loading GtkBuilder UI.
+ * Otherwise, you probably want gtk_builder_new_from_file() instead.
  *
  * If an error occurs, 0 will be returned and @error will be assigned a
  * #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_FILE_ERROR
@@ -1367,7 +1366,9 @@ gtk_builder_extend_with_template (GtkBuilder   *builder,
  * Parses a resource file containing a [GtkBuilder UI definition][BUILDER-UI]
  * and merges it with the current contents of @builder.
  *
- * Most users will probably want to use gtk_builder_new_from_resource().
+ * This function is useful if you need to call gtk_builder_set_current_object()
+ * to add user data to callbacks before loading GtkBuilder UI.
+ * Otherwise, you probably want gtk_builder_new_from_resource() instead.
  *
  * If an error occurs, 0 will be returned and @error will be assigned a
  * #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or #G_RESOURCE_ERROR
@@ -1517,7 +1518,9 @@ gtk_builder_add_objects_from_resource (GtkBuilder   *builder,
  * Parses a string containing a [GtkBuilder UI definition][BUILDER-UI]
  * and merges it with the current contents of @builder.
  *
- * Most users will probably want to use gtk_builder_new_from_string().
+ * This function is useful if you need to call gtk_builder_set_current_object()
+ * to add user data to callbacks before loading GtkBuilder UI.
+ * Otherwise, you probably want gtk_builder_new_from_string() instead.
  *
  * Upon errors %FALSE will be returned and @error will be assigned a
  * #GError from the #GTK_BUILDER_ERROR, #G_MARKUP_ERROR or