[gtk] Box, Grid: Improve various bits of documentation

[Daniel Boles <dboles src gnome org>]

commit 72d09d22e934c52ff301c0754078f1e42e97bc69
Author: Daniel Boles <dboles src gmail com>
Date:   Tue Dec 4 20:37:08 2018 +0000

    Box, Grid: Improve various bits of documentation
    
    Issue #1495 showed that the docs of GtkGrid retain outdated implications
    that (as was once, but is no longer, the case) it is intended to replace
    GtkBox, by discussing HfW and widget properties in a way that suggests
    GtkBox can't handle them. But of course it does, and it's preferable for
    simple single-row/column cases. Worse, we said GtkGrid “provides exactly
    the same functionality” for the latter case, but the original point of
    that Issues was that it doesn’t, at least for CSS positional selectors!
    
    Box:
    • Use an actually meaningful @Short_description.
    • Remove unhelpful @See_also references to unrelated containers.
    • Remove references to “rectangular area”: it might be another shape
      via CSS, or “rectangular” might falsely imply 2 dimensions of children.
    • Mention Orientable:orientation.
    • Emphasise usefulness of :[hv]align for allocating in the other axis.
    • Don’t say that Grid “provides exactly the same functionality” for a
      single row or column, since (A) it is overkill for that case and (B)
      said Issue proved that it *doesn’t* for CSS child order, for example.
    
    Grid:
    • Don’t dwell on widget properties and height-for-width in a way that
      wrongly implies that Box can’t handle those (or Grid can better). In
      fact, just get rid of that bit altogether: Box handles them fine, and
      such wording was only needed years ago for migration from GTK+ 2 to 3.
    • Point to GtkBox as being preferred for the simple row/column use case.

 gtk/gtkbox.c  | 18 +++++++-----------
 gtk/gtkgrid.c |  8 +++-----
 2 files changed, 10 insertions(+), 16 deletions(-)
---
diff --git a/gtk/gtkbox.c b/gtk/gtkbox.c
index 21f0d226ce..fdf000db2c 100644
--- a/gtk/gtkbox.c
+++ b/gtk/gtkbox.c
@@ -24,16 +24,15 @@
 
 /**
  * SECTION:gtkbox
- * @Short_description: A container box
+ * @Short_description: A container for packing widgets in a single row or column
  * @Title: GtkBox
- * @See_also: #GtkFrame, #GtkGrid, #GtkLayout
+ * @See_also: #GtkGrid
  *
- * The GtkBox widget organizes child widgets into a rectangular area.
- *
- * 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.
+ * The GtkBox widget arranges child widgets into a single row or column,
+ * depending upon the value of its #GtkOrientable:orientation property. Within
+ * the other dimension, all children are allocated the same size. Of course,
+ * the #GtkWidget:halign and #GtkWidget:valign properties can be used on
+ * the children to influence their allocation.
  *
  * GtkBox uses a notion of packing. Packing refers
  * to adding widgets with reference to a particular position in a
@@ -62,9 +61,6 @@
  * Use gtk_box_reorder_child() to move a GtkBox child to a different
  * place in the box.
  *
- * Note that a single-row or single-column #GtkGrid provides exactly
- * the same functionality as #GtkBox.
- *
  * # CSS nodes
  *
  * GtkBox uses a single CSS node with name box.
diff --git a/gtk/gtkgrid.c b/gtk/gtkgrid.c
index 553dc485e2..68c66adb52 100644
--- a/gtk/gtkgrid.c
+++ b/gtk/gtkgrid.c
@@ -39,10 +39,7 @@
  * @See_also: #GtkBox
  *
  * GtkGrid is a container which arranges its child widgets in
- * rows and columns. It is a very similar to #GtkBox,
- * but it consistently uses #GtkWidget’s #GtkWidget:margin and #GtkWidget:expand
- * properties instead of custom child properties, and it fully supports
- * [height-for-width geometry management][geometry-management].
+ * rows and columns, with arbitrary positions and horizontal/vertical spans.
  *
  * Children are added using gtk_grid_attach(). They can span multiple
  * rows or columns. It is also possible to add a child next to an
@@ -51,7 +48,8 @@
  *
  * GtkGrid can be used like a #GtkBox by just using gtk_container_add(),
  * which will place children next to each other in the direction determined
- * by the #GtkOrientable:orientation property.
+ * by the #GtkOrientable:orientation property. However, if all you want is a
+ * single row or column, then #GtkBox is the preferred widget.
  *
  * # CSS nodes
  *