1 files changed, 67 insertions, 13 deletions

diff --git a/gtk/gtkvbbox.c b/gtk/gtkvbbox.c
index 72ba3851b..c6bf3696c 100644
--- a/gtk/gtkvbbox.c
+++ b/gtk/gtkvbbox.c
@@ -30,6 +30,30 @@
 #include "gtkintl.h"
 #include "gtkalias.h"
 
+/**
+ * SECTION:gtkvbbox
+ * @Short_description: A container for arranging buttons vertically
+ * @Title: GtkVButtonBox
+ * @See_also: #GtkBox, #GtkButtonBox, #GtkHButtonBox
+ *
+ * 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.
+ *
+ * A #GtkVButtonBox is created with gtk_vbutton_box_new(). Buttons are
+ * packed into a button box the same way widgets are added to any other
+ * container, using gtk_container_add(). You can also use
+ * gtk_box_pack_start() or gtk_box_pack_end(), but for button boxes both
+ * these functions work just like gtk_container_add(), ie., they pack the
+ * button in a way that depends on the current layout style and on
+ * whether the button has had gtk_button_box_set_child_secondary() called
+ * on it.
+ *
+ * The spacing between buttons can be set with gtk_box_set_spacing(). The
+ * arrangement and layout of the buttons can be changed with
+ * gtk_button_box_set_layout().
+ */
 
 static gint default_spacing = 10;
 static GtkButtonBoxStyle default_layout_style = GTK_BUTTONBOX_EDGE;
@@ -48,25 +72,42 @@ gtk_vbutton_box_init (GtkVButtonBox *vbutton_box)
                                   GTK_ORIENTATION_VERTICAL);
 }
 
+/**
+ * gtk_vbutton_box_new:
+ *
+ * Creates a new vertical button box.
+ *
+ * Returns: a new button box #GtkWidget.
+ */
 GtkWidget *
 gtk_vbutton_box_new (void)
 {
   return g_object_new (GTK_TYPE_VBUTTON_BOX, NULL);
 }
 
-
-
-/* set default value for spacing */
-
+/**
+ * gtk_vbutton_box_set_spacing_default:
+ * @spacing: an integer value.
+ *
+ * Changes the default spacing that is placed between widgets in an
+ * vertical button box.
+ *
+ * Deprecated: 2.0: Use gtk_box_set_spacing() instead.
+ */
 void
 gtk_vbutton_box_set_spacing_default (gint spacing)
 {
   default_spacing = spacing;
 }
 
-
-/* set default value for layout style */
-
+/**
+ * gtk_vbutton_box_set_layout_default:
+ * @layout: a new #GtkButtonBoxStyle.
+ *
+ * Sets a new layout mode that will be used by all button boxes.
+ *
+ * Deprecated: 2.0: Use gtk_button_box_set_layout() instead.
+ */
 void
 gtk_vbutton_box_set_layout_default (GtkButtonBoxStyle layout)
 {
@@ -76,18 +117,31 @@ gtk_vbutton_box_set_layout_default (GtkButtonBoxStyle layout)
   default_layout_style = layout;
 }
 
-/* get default value for spacing */
-
+/**
+ * gtk_vbutton_box_get_spacing_default:
+ *
+ * Retrieves the current default spacing for vertical button boxes. This is the number of pixels
+ * to be placed between the buttons when they are arranged.
+ *
+ * Returns: the default number of pixels between buttons.
+ *
+ * Deprecated: 2.0: Use gtk_box_get_spacing() instead.
+ */
 gint
 gtk_vbutton_box_get_spacing_default (void)
 {
   return default_spacing;
 }
 
-
-
-/* get default value for layout style */
-
+/**
+ * gtk_vbutton_box_get_layout_default:
+ *
+ * Retrieves the current layout used to arrange buttons in button box widgets.
+ *
+ * Returns: the current #GtkButtonBoxStyle.
+ *
+ * Deprecated: 2.0: Use gtk_button_box_get_layout() instead.
+ */
 GtkButtonBoxStyle
 gtk_vbutton_box_get_layout_default (void)
 {