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.
• Note in the child properties that are remove in master that we have
  better, preferred alternatives available now in GtkWidget/CSS props.
  There’s no nice way to deprecate these, though they’re gone in GTK+ 4.
• Correct a copy-paste-o from the blurb of :expand to :fill.

Grid:
• Remove references to deprecated widgets: GtkTable and Gtk[HV]Box.
• 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
  Table is so old as to be not worth mentioning (in anything except the
  2 => 3 migration guide) and points to Grid in its deprecation notice.
• Point to GtkBox as being preferred for the simple row/column use case.

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 GtkBox widget arranges child widgets into a single row or column,
- *
+ * depending upon the value of its #GtkOrientable:orientation property. Within
- * The rectangular area of a GtkBox is organized into either a single row
+ * the other dimension, all children are allocated the same size. Of course,
- * or a single column of child widgets depending upon the orientation.
+ * the #GtkWidget:halign and #GtkWidget:valign properties can be used on
- * Thus, all children of a GtkBox are allocated one dimension in common,
+ * the children to influence their allocation.
- * which is the height of a row, or the width of a column.
  *
  * GtkBox uses a notion of packing. Packing refers
  * to adding widgets with reference to a particular position in a
@@ -69,9 +68,6 @@
  * fill and padding child properties.
  * Use gtk_box_query_child_packing() to query these fields.
  *
- * 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.
@@ -310,9 +306,9 @@ gtk_box_class_init (GtkBoxClass *class)
    * but #GtkHBox, #GtkVBox and other subclasses use the old default
    * of %TRUE.
    *
-   * Note that the #GtkWidget:halign, #GtkWidget:valign, #GtkWidget:hexpand
+   * Note: The #GtkWidget:hexpand or #GtkWidget:vexpand properties are the
-   * and #GtkWidget:vexpand properties are the preferred way to influence
+   * preferred way to influence whether the child receives extra space, by
-   * child size allocation in containers.
+   * setting the child’s expand property corresponding to the box’s orientation.
    *
    * In contrast to #GtkWidget:hexpand, the expand child property does
    * not cause the box to expand itself.
@@ -327,11 +323,12 @@ gtk_box_class_init (GtkBoxClass *class)
   /**
    * GtkBox:fill:
    *
-   * Whether the child should receive extra space when the parent grows.
+   * Whether the child should fill extra space or use it as padding.
    *
-   * Note that the #GtkWidget:halign, #GtkWidget:valign, #GtkWidget:hexpand
+   * Note: The #GtkWidget:halign or #GtkWidget:valign properties are the
-   * and #GtkWidget:vexpand properties are the preferred way to influence
+   * preferred way to influence whether the child fills available space, by
-   * child size allocation in containers.
+   * setting the child’s align property corresponding to the box’s orientation
+   * to %GTK_ALIGN_FILL to fill, or to something else to refrain from filling.
    */
   child_props[CHILD_PROP_FILL] =
       g_param_spec_boolean ("fill",
@@ -340,6 +337,14 @@ gtk_box_class_init (GtkBoxClass *class)
                             TRUE,
                             GTK_PARAM_READWRITE);
 
+  /**
+   * GtkBox:padding:
+   *
+   * Extra space to put between the child and its neighbors, in pixels.
+   *
+   * Note: The CSS padding properties are the preferred way to add space among
+   * widgets, by setting the paddings corresponding to the box’s orientation.
+   */
   child_props[CHILD_PROP_PADDING] =
       g_param_spec_uint ("padding",
                          P_("Padding"),

gtk/gtkgrid.c

@@ -36,13 +36,10 @@
  * SECTION:gtkgrid
  * @Short_description: Pack widgets in rows and columns
  * @Title: GtkGrid
- * @See_also: #GtkTable, #GtkHBox, #GtkVBox
+ * @See_also: #GtkBox
  *
  * GtkGrid is a container which arranges its child widgets in
- * rows and columns. It is a very similar to #GtkTable and #GtkBox,
+ * rows and columns, with arbitrary positions and horizontal/vertical spans.
- * 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].
  *
  * 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
  *