Box, etc: Improve docs after H* and V* deprecations.

Stop documenting the base class as just a base class for the
H and V specializations, copying the useful descriptions from
those H/V classes to the base class. Do not advise the use of
the H/V classes or refer to them unnecessarily.

gtk/gtkbbox.c

@@ -26,12 +26,13 @@
 
 /**
  * SECTION:gtkbbox
- * @Short_description: Base class for GtkHButtonBox and GtkVButtonBox
+ * @Short_description: A container for arranging buttons
  * @Title: GtkButtonBox
- * @See_also: #GtkVButtonBox, #GtkHButtonBox
  *
- * The primary purpose of this class is to keep track of the various
+ * A button box should be used to provide a consistent layout of buttons
- * properties of #GtkHButtonBox and #GtkVButtonBox widgets.
+ * throughout your application. The layout/spacing can be altered by the
+ * programmer, or if desired, by the user to alter the 'feel' of a
+ * program to a small degree.
  *
  * gtk_button_box_get_layout() and gtk_button_box_set_layout() retrieve and
  * alter the method used to spread the buttons in a button box across the

gtk/gtkbox.c

@@ -26,18 +26,15 @@
 
 /**
  * SECTION:gtkbox
- * @Short_description: Base class for box containers
+ * @Short_description: A container box
  * @Title: GtkBox
- * @See_also: #GtkHBox, #GtkVBox, #GtkFrame, #GtkTable, #GtkLayout
+ * @See_also: #GtkFrame, #GtkTable, #GtkLayout
  *
- * GtkBox is an widget which encapsulates functionality for a
+ * The GtkBox widget organizes child widgets into a rectangular area.
- * particular kind of container, one that organizes a variable number of
- * widgets into a rectangular area.  GtkBox has a number of derived
- * classes, e.g. #GtkHBox and #GtkVBox.
  *
  * The rectangular area of a GtkBox is organized into either a single row
- * or a single column of child widgets depending upon whether the box is
+ * or a single column of child widgets depending upon the orientation.
- * of type #GtkHBox or #GtkVBox, respectively.  Thus, all children of a
+ * 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.
  *
@@ -45,8 +42,8 @@
  * 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 #GtkVBox, the start is defined as the top of the box and the end is
+ * For a vertical #GtkBox, the start is defined as the top of the box and the end is
- * defined as the bottom.  For a #GtkHBox the start is defined as the
+ * 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
@@ -1386,8 +1383,8 @@ gtk_box_new (GtkOrientation orientation,
  * @fill: %TRUE if space given to @child by the @expand option is
  *     actually allocated to @child, rather than just padding it.  This
  *     parameter has no effect if @expand is set to %FALSE.  A child is
- *     always allocated the full height of a #GtkHBox and the full width
+ *     always allocated the full height of a horizontal #GtkBox and the full width
- *     of a #GtkVBox. This option affects the other dimension
+ *     of a vertical #GtkBox. This option affects the other dimension
  * @padding: extra space in pixels to put between this child and its
  *   neighbors, over and above the global amount specified by
  *   #GtkBox:spacing property.  If @child is a widget at one of the
@@ -1418,8 +1415,8 @@ gtk_box_pack_start (GtkBox    *box,
  * @fill: %TRUE if space given to @child by the @expand option is
  *   actually allocated to @child, rather than just padding it.  This
  *   parameter has no effect if @expand is set to %FALSE.  A child is
- *   always allocated the full height of a #GtkHBox and the full width
+ *   always allocated the full height of a horizontal #GtkBox and the full width
- *   of a #GtkVBox.  This option affects the other dimension
+ *   of a vertical #GtkBox.  This option affects the other dimension
  * @padding: extra space in pixels to put between this child and its
  *   neighbors, over and above the global amount specified by
  *   #GtkBox:spacing property.  If @child is a widget at one of the

gtk/gtkpaned.c

@@ -40,11 +40,15 @@
 
 /**
  * SECTION:gtkpaned
- * @Short_description: Base class for widgets with two adjustable panes
+ * @Short_description: A widget with two adjustable panes
  * @Title: GtkPaned
  *
- * #GtkPaned is the base class for widgets with two panes, arranged either
+ * #GtkPaned has two panes, arranged either
- * horizontally (#GtkHPaned) or vertically (#GtkVPaned). Child widgets are
+ * horizontally or vertically. The division between
+ * the two panes is adjustable by the user by dragging
+ * a handle. See #GtkPaned for details.
+ *
+ * Child widgets are
  * added to the panes of the widget with gtk_paned_pack1() and
  * gtk_paned_pack2(). The division between the two children is set by default
  * from the size requests of the children, but it can be adjusted by the

gtk/gtkscale.c

@@ -45,7 +45,7 @@
 
 /**
  * SECTION:gtkscale
- * @Short_description: Base class for GtkHScale and GtkVScale
+ * @Short_description: A slider widget for selecting a value from a range
  * @Title: GtkScale
  *
  * A GtkScale is a slider control used to select a numeric value. 

gtk/gtkscrollbar.c

@@ -34,14 +34,12 @@
 
 /**
  * SECTION:gtkscrollbar
- * @Short_description: Base class for GtkHScrollbar and GtkVScrollbar
+ * @Short_description: A Scrollbar
  * @Title: GtkScrollbar
- * @See_also: #GtkHScrollbar, #GtkVScrollbar, #GtkAdjustment,
+ * @See_also: #GtkAdjustment, #GtkScrolledWindow
- *   #GtkScrolledWindow
  *
- * The #GtkScrollbar widget is the base class for #GtkHScrollbar and
+ * The #GtkScrollbar widget is a horizontal or vertical scrollbar,
- * #GtkVScrollbar. It can be used in the same way as these, by setting
+ * depending on the value of the "orientation" property.
- * the "orientation" property appropriately.
  *
  * The position of the thumb in a scrollbar is controlled by the scroll
  * adjustments. See #GtkAdjustment for the fields in an adjustment - for

gtk/gtkseparator.c

@@ -33,12 +33,13 @@
 
 /**
  * SECTION:gtkseparator
- * @Short_description: Base class for GtkHSeparator and GtkVSeparator
+ * @Short_description: A separator widget
  * @Title: GtkSeparator
  *
- * The GtkSeparator widget is the base class for #GtkHSeparator and
+ * GtkSeparator is a horizontal or vertical separator widget, depending on the 
- * #GtkVSeparator. It can be used in the same way as these, by setting
+ * value of the "orientation" property, used to group the widgets within a 
- * the "orientation" property suitably.
+ * window. It displays a line with a shadow to make it appear sunken into the 
+ * interface.
  */