diff --git a/gtk/gtkhbox.c b/gtk/gtkhbox.c
index cade45446f..dd6cd29113 100644
--- a/gtk/gtkhbox.c
+++ b/gtk/gtkhbox.c
@@ -44,7 +44,10 @@
  *
  * All children are allocated the same height.
  *
- * GtkHBox has been deprecated, use #GtkBox instead.
+ * GtkHBox has been deprecated, you can use #GtkBox instead, which is a very
+ * quick and easy change. But the recommendation is to switch to #GtkGrid, since
+ * #GtkBox is going to go away eventually.
+ * See <xref linkend="gtk-migrating-GtkGrid"/>
  */
 
 
@@ -73,7 +76,10 @@ gtk_hbox_init (GtkHBox *hbox)
  *
  * Returns: a new #GtkHBox.
  *
- * Deprecated: 3.2: Use gtk_box_new() with %GTK_ORIENTATION_HORIZONTAL instead
+ * Deprecated: 3.2: You can use gtk_box_new() with %GTK_ORIENTATION_HORIZONTAL instead,
+ *   wich is a very quick and easy change. But the recommendation is to switch to
+ *   #GtkGrid, since #GtkBox is going to go away eventually.
+ *   See <xref linkend="gtk-migrating-GtkGrid"/>.
  */
 GtkWidget *
 gtk_hbox_new (gboolean homogeneous,
diff --git a/gtk/gtkvbox.c b/gtk/gtkvbox.c
index f7f91f6088..ea05e99742 100644
--- a/gtk/gtkvbox.c
+++ b/gtk/gtkvbox.c
@@ -44,7 +44,10 @@
  *
  * All children are allocated the same width.
  *
- * GtkVBox has been deprecated, use #GtkBox instead.
+ * GtkVBox has been deprecated, you can use #GtkBox instead, which is a very
+ * quick and easy change. But the recommendation is to switch to #GtkGrid, since
+ * #GtkBox is going to go away eventually.
+ * See <xref linkend="gtk-migrating-GtkGrid"/>
  */
 
 G_DEFINE_TYPE (GtkVBox, gtk_vbox, GTK_TYPE_BOX)
@@ -72,7 +75,10 @@ gtk_vbox_init (GtkVBox *vbox)
  *
  * Returns: a new #GtkVBox.
  *
- * Deprecated: 3.2: Use gtk_box_new() with %GTK_ORIENTATION_VERTICAL instead
+ * Deprecated: 3.2: You can use gtk_box_new() with %GTK_ORIENTATION_VERTICAL instead,
+ *   wich is a very quick and easy change. But the recommendation is to switch to
+ *   #GtkGrid, since #GtkBox is going to go away eventually.
+ *   See <xref linkend="gtk-migrating-GtkGrid"/>.
  */
 GtkWidget *
 gtk_vbox_new (gboolean homogeneous,