[gtk+] Expand migration hints for h/v boxes

[Matthias Clasen <matthiasc src gnome org>]

commit 2204405c9c9ac90ff250aeb4540c78feb9316bab
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Jun 10 17:40:16 2011 -0400

    Expand migration hints for h/v boxes

 gtk/gtkbox.c  |   39 ++++++++++++++++++---------------------
 gtk/gtkhbox.c |   14 ++++++++++----
 gtk/gtkvbox.c |   18 ++++++++++++++----
 3 files changed, 42 insertions(+), 29 deletions(-)
---
diff --git a/gtk/gtkbox.c b/gtk/gtkbox.c
index 2f97882..a592e81 100644
--- a/gtk/gtkbox.c
+++ b/gtk/gtkbox.c
@@ -34,27 +34,26 @@
  *
  * The rectangular area of a GtkBox is organized into either a single row
  * or a single column of child widgets depending upon the orientation.
- * Thus, all children of a
- * GtkBox are allocated one dimension in common, which is the height of a
- * row, or the width of a column.
+ * Thus, all children of a GtkBox are allocated one dimension in common,
+ * which is the height of a row, or the width of a column.
  *
- * GtkBox uses a notion of <emphasis>packing</emphasis>.  Packing
- * refers to adding widgets with reference to a particular position in a
- * #GtkContainer.  For a GtkBox, there are two reference positions: the
+ * GtkBox uses a notion of <emphasis>packing</emphasis>. Packing refers
+ * to adding widgets with reference to a particular position in a
+ * #GtkContainer. For a GtkBox, there are two reference positions: the
  * <emphasis>start</emphasis> and the <emphasis>end</emphasis> of the box.
- * For a vertical #GtkBox, the start is defined as the top of the box and the end is
- * defined as the bottom.  For a horizontal #GtkBox the start is defined as the
- * left side and the end is defined as the right side.
+ * For a vertical #GtkBox, the start is defined as the top of the box and
+ * the end is defined as the bottom. For a horizontal #GtkBox the start
+ * is defined as the left side and the end is defined as the right side.
  *
  * Use repeated calls to gtk_box_pack_start() to pack widgets into a
- * GtkBox from start to end.  Use gtk_box_pack_end() to add widgets from
- * end to start.  You may intersperse these calls and add widgets from
+ * GtkBox from start to end. Use gtk_box_pack_end() to add widgets from
+ * end to start. You may intersperse these calls and add widgets from
  * both ends of the same GtkBox.
  *
- * Because GtkBox is a #GtkContainer, you may also use
- * gtk_container_add() to insert widgets into the box, and they will be
- * packed with the default values for #GtkBox:expand and #GtkBox:fill.
- * Use gtk_container_remove() to remove widgets from the GtkBox.
+ * Because GtkBox is a #GtkContainer, you may also use gtk_container_add()
+ * to insert widgets into the box, and they will be packed with the default
+ * values for #GtkBox:expand and #GtkBox:fill. Use gtk_container_remove()
+ * to remove widgets from the GtkBox.
  *
  * Use gtk_box_set_homogeneous() to specify whether or not all children
  * of the GtkBox are forced to get the same amount of space.
@@ -72,12 +71,10 @@
  * #GtkBox:fill and #GtkBox:padding child properties.
  * Use gtk_box_query_child_packing() to query these fields.
  *
- * <note>
- * <para>
- * Note that a single-row or single-column #GtkGrid provides exactly the
- * same functionality as #GtkBox.
- * </para>
- * </note>
+ * <note><para>
+ * Note that a single-row or single-column #GtkGrid provides exactly
+ * the same functionality as #GtkBox.
+ * </para></note>
  */
 
 #include "config.h"
diff --git a/gtk/gtkhbox.c b/gtk/gtkhbox.c
index dd6cd29..5ade71d 100644
--- a/gtk/gtkhbox.c
+++ b/gtk/gtkhbox.c
@@ -44,10 +44,16 @@
  *
  * All children are allocated the same height.
  *
- * 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"/>
+ * GtkHBox has been deprecated. You can use #GtkBox instead, which is a
+ * very quick and easy change. If you have derived your own classes from
+ * GtkHBox, you can simply change the inheritance to derive directly
+ * from #GtkBox. No further changes are needed, since the default
+ * value of the #GtkOrientable::orientation property is
+ * %GTK_ORIENTATION_HORIZONTAL.
+ * If you want your code to be future-proof, the recommendation is to
+ * switch to #GtkGrid, since #GtkBox is going to be deprecated in favor
+ * of the more flexible grid widget eventually. For more information
+ * about migrating to #GtkGrid, see <xref linkend="gtk-migrating-GtkGrid"/>
  */
 
 
diff --git a/gtk/gtkvbox.c b/gtk/gtkvbox.c
index ea05e99..0cffaea 100644
--- a/gtk/gtkvbox.c
+++ b/gtk/gtkvbox.c
@@ -44,10 +44,20 @@
  *
  * All children are allocated the same width.
  *
- * 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"/>
+ * 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:
+ * |[
+ *   gtk_orientable_set_orientation (GTK_ORIENTABLE (object),
+ *                                   GTK_ORIENTATION_VERTICAL);
+ * ]|
+ * If you want your code to be future-proof, the recommendation is to
+ * switch to #GtkGrid, since #GtkBox is going to be deprecated in favor
+ * of the more flexible #GtkGrid widget eventually.
+ * See <xref linkend="gtk-migrating-GtkGrid"/>.
  */
 
 G_DEFINE_TYPE (GtkVBox, gtk_vbox, GTK_TYPE_BOX)