[gtk+] Box, etc: Improve docs after H* and V* deprecations.

[Murray Cumming <murrayc src gnome org>]

commit 151bcc6dfad970285f97e44eece97f2d725efe5a
Author: Murray Cumming <murrayc murrayc com>
Date:   Thu Jun 9 22:59:38 2011 +0200

    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      |    9 +++++----
 gtk/gtkbox.c       |   25 +++++++++++--------------
 gtk/gtkpaned.c     |   10 +++++++---
 gtk/gtkscale.c     |    4 ++--
 gtk/gtkscrollbar.c |   10 ++++------
 gtk/gtkseparator.c |    9 +++++----
 6 files changed, 34 insertions(+), 33 deletions(-)
---
diff --git a/gtk/gtkbbox.c b/gtk/gtkbbox.c
index e5659a8..57d87af 100644
--- a/gtk/gtkbbox.c
+++ b/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
- * properties of #GtkHButtonBox and #GtkVButtonBox widgets.
+ * A button box should be used to provide a consistent layout of buttons
+ * 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
diff --git a/gtk/gtkbox.c b/gtk/gtkbox.c
index a0d7b17..2f97882 100644
--- a/gtk/gtkbox.c
+++ b/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
- * 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 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 whether the box is
- * of type #GtkHBox or #GtkVBox, respectively.  Thus, all children of a
+ * 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.
  *
@@ -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
- * defined as the bottom.  For a #GtkHBox the start is defined as the
+ * 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
@@ -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
- *     of a #GtkVBox. This option affects the other dimension
+ *     always allocated the full height of a horizontal #GtkBox and the full width
+ *     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
- *   of a #GtkVBox.  This option affects the other dimension
+ *   always allocated the full height of a horizontal #GtkBox and the full width
+ *   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
diff --git a/gtk/gtkpaned.c b/gtk/gtkpaned.c
index e7b334a..7c6ab6c 100644
--- a/gtk/gtkpaned.c
+++ b/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
- * horizontally (#GtkHPaned) or vertically (#GtkVPaned). Child widgets are
+ * #GtkPaned has two panes, arranged either
+ * 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
diff --git a/gtk/gtkscale.c b/gtk/gtkscale.c
index 95ce6ba..6969741 100644
--- a/gtk/gtkscale.c
+++ b/gtk/gtkscale.c
@@ -45,10 +45,10 @@
 
 /**
  * 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.
+ * A GtkScale is a slider control used to select a numeric value. 
  * To use it, you'll probably want to investigate the methods on
  * its base class, #GtkRange, in addition to the methods for GtkScale itself.
  * To set the value of a scale, you would normally use gtk_range_set_value().
diff --git a/gtk/gtkscrollbar.c b/gtk/gtkscrollbar.c
index 4a852f2..4cce474 100644
--- a/gtk/gtkscrollbar.c
+++ b/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,
- *   #GtkScrolledWindow
+ * @See_also: #GtkAdjustment, #GtkScrolledWindow
  *
- * The #GtkScrollbar widget is the base class for #GtkHScrollbar and
- * #GtkVScrollbar. It can be used in the same way as these, by setting
- * the "orientation" property appropriately.
+ * The #GtkScrollbar widget is a horizontal or vertical scrollbar,
+ * depending on the value of the "orientation" property.
  *
  * The position of the thumb in a scrollbar is controlled by the scroll
  * adjustments. See #GtkAdjustment for the fields in an adjustment - for
diff --git a/gtk/gtkseparator.c b/gtk/gtkseparator.c
index 013247a..4c723f1 100644
--- a/gtk/gtkseparator.c
+++ b/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
- * #GtkVSeparator. It can be used in the same way as these, by setting
- * the "orientation" property suitably.
+ * GtkSeparator is a horizontal or vertical separator widget, depending on the 
+ * value of the "orientation" property, used to group the widgets within a 
+ * window. It displays a line with a shadow to make it appear sunken into the 
+ * interface.
  */