From d1936c1ae3e5e133d95477cb4db3724f0de42f0c Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Fri, 8 Nov 2019 18:02:13 +0000
Subject: [PATCH] docs: Clarify when to replace old boxes with Grid

Mention that GtkGrid should only replace grid-like layouts achieved with
nested boxes.

Additionally, remove any mention of "future proofing": boxes are not
going away.
---
 gtk/deprecated/gtkhbox.c |  9 +++++----
 gtk/deprecated/gtkvbox.c | 24 ++++++++++++++----------
 2 files changed, 19 insertions(+), 14 deletions(-)

diff --git a/gtk/deprecated/gtkhbox.c b/gtk/deprecated/gtkhbox.c
index 433ba75574..7844d81bb8 100644
--- a/gtk/deprecated/gtkhbox.c
+++ b/gtk/deprecated/gtkhbox.c
@@ -50,10 +50,11 @@ G_GNUC_BEGIN_IGNORE_DEPRECATIONS
  * from #GtkBox. No further changes are needed, since the default
  * value of the #GtkOrientable:orientation property is
  * %GTK_ORIENTATION_HORIZONTAL.
- * If you don’t need first-child or last-child styling, and want your code
- * to be future-proof, the recommendation is to switch to #GtkGrid instead
- * of nested boxes. For more information about migrating to #GtkGrid,
- * see [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid].
+ *
+ * If you have a grid-like layout composed of nested boxes, and you don’t
+ * need first-child or last-child styling, the recommendation is to switch
+ * to #GtkGrid. For more information about migrating to #GtkGrid, see
+ * [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid].
  */
 
 
diff --git a/gtk/deprecated/gtkvbox.c b/gtk/deprecated/gtkvbox.c
index 993f5950fd..b8ef2e445b 100644
--- a/gtk/deprecated/gtkvbox.c
+++ b/gtk/deprecated/gtkvbox.c
@@ -45,20 +45,24 @@ G_GNUC_BEGIN_IGNORE_DEPRECATIONS
  *
  * All children are allocated the same width.
  *
- * GtkVBox has been deprecated. You can use #GtkBox instead, which is a
- * very quick and easy change. If you have derived your own classes from
- * GtkVBox, you can simply change the inheritance to derive directly
- * from #GtkBox, and set the #GtkOrientable:orientation property to
- * %GTK_ORIENTATION_VERTICAL in your instance init function, with a
- * call like:
+ * GtkVBox has been deprecated. You can use #GtkBox with a #GtkOrientable:orientation
+ * set to %GTK_ORIENTATION_VERTICAL instead when calling gtk_box_new(),
+ * which is a very quick and easy change.
+ *
+ * If you have derived your own classes from GtkVBox, you can change the
+ * inheritance to derive directly from #GtkBox, and set the #GtkOrientable:orientation
+ * property to %GTK_ORIENTATION_VERTICAL in your instance init function,
+ * with a call like:
+ *
  * |[<!-- language="C" -->
  *   gtk_orientable_set_orientation (GTK_ORIENTABLE (object),
  *                                   GTK_ORIENTATION_VERTICAL);
  * ]|
- * If you don’t need first-child or last-child styling and want your code
- * to be future-proof, the recommendation is to switch to #GtkGrid instead
- * of nested boxes. For more information about migrating to #GtkGrid,
- * see [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid].
+ *
+ * If you have a grid-like layout composed of nested boxes, and you don’t
+ * need first-child or last-child styling, the recommendation is to switch
+ * to #GtkGrid. For more information about migrating to #GtkGrid, see
+ * [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid].
  */
 
 G_DEFINE_TYPE (GtkVBox, gtk_vbox, GTK_TYPE_BOX)