[gtk+] Move documentation to inline comments: GtkBox

[Javier Jardón <jjardon src gnome org>]

commit ef4e7b247358c8c4fa67f8339f986831d06b66c9
Author: Tadej Borovšak <tadeboro gmail com>
Date:   Tue Mar 9 23:51:03 2010 +0100

    Move documentation to inline comments: GtkBox
    
    Fixes https://bugzilla.gnome.org/show_bug.cgi?id=611742
    
    Signed-off-by: Javier Jardón <jjardon gnome org>

 docs/reference/gtk/tmpl/.gitignore  |    1 +
 docs/reference/gtk/tmpl/gtkbox.sgml |  291 -----------------------------------
 gtk/gtkbox.c                        |   54 +++++++
 gtk/gtkbox.h                        |   22 +++
 4 files changed, 77 insertions(+), 291 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index a9378ad..14c568a 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -1,3 +1,4 @@
+gtkbox.sgml
 gtkhbox.sgml
 gtkmessagedialog.sgml
 gtktesting.sgml
diff --git a/gtk/gtkbox.c b/gtk/gtkbox.c
index 1ebcbcf..d9356f5 100644
--- a/gtk/gtkbox.c
+++ b/gtk/gtkbox.c
@@ -24,6 +24,60 @@
  * GTK+ at ftp://ftp.gtk.org/pub/gtk/.
  */
 
+/**
+ * SECTION:gtkbox
+ * @Short_description: Base class for box containers
+ * @Title: GtkBox
+ * @See_also:i #GtkHBox, #GtkVBox, #GtkFrame, #GtkTable, #GtkLayout
+ *
+ * GtkBox is an abstract 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 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
+ * GtkBox are allocated one dimension in common, which is the height of a
+ * row, or the width of a column.
+ *
+ * GtkBox uses a notion of <emphasis>packing</emphasis>.  Packing 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
+ * left side and the end is defined as the right side.
+ *
+ * Use repeated calls to gtk_box_pack_start() to pack widgets into a
+ * GtkBox from start to end.  Use gtk_box_pack_end() to add widgets from
+ * end to start.  You may intersperse these calls and add widgets from
+ * both ends of the same GtkBox.
+ *
+ * Use gtk_box_pack_start_defaults() or gtk_box_pack_end_defaults()
+ * to pack widgets into a GtkBox if you do not need to specify the
+ * #GtkBox:expand, #GtkBox:fill, or #GtkBox:padding child properties
+ * for the child to be added.
+ *
+ * Because GtkBox is a #GtkContainer, you may also use
+ * gtk_container_add() to insert widgets into the box, and they will be
+ * packed as if with gtk_box_pack_start_defaults().  Use
+ * gtk_container_remove() to remove widgets from the GtkBox.
+ *
+ * Use gtk_box_set_homogeneous() to specify whether or not all children
+ * of the GtkBox are forced to get the same amount of space.
+ *
+ * Use gtk_box_set_spacing() to determine how much space will be
+ * minimally placed between all children in the GtkBox.
+ *
+ * Use gtk_box_reorder_child() to move a GtkBox child to a different
+ * place in the box.
+ *
+ * Use gtk_box_set_child_packing() to reset the #GtkBox:expand,
+ * #GtkBox:fill and #GtkBox:padding child properties.
+ * Use gtk_box_query_child_packing() to query these fields.
+ */
+
 #include "config.h"
 
 #include "gtkbox.h"
diff --git a/gtk/gtkbox.h b/gtk/gtkbox.h
index 914683b..038c3b1 100644
--- a/gtk/gtkbox.h
+++ b/gtk/gtkbox.h
@@ -65,6 +65,28 @@ struct _GtkBoxClass
   GtkContainerClass parent_class;
 };
 
+/**
+ * GtkBoxChild:
+ * @widget: the child widget, packed into the GtkBox.
+ * @padding: the number of extra pixels to put between this child and its
+ *  neighbors, set when packed, zero by default.
+ * @expand: flag indicates whether extra space should be given to this child.
+ *  Any extra space given to the parent GtkBox is divided up among all children
+ *  with this attribute set to %TRUE; set when packed, %TRUE by default.
+ * @fill: flag indicates whether any extra space given to this child due to its
+ *  @expand attribute being set is actually allocated to the child, rather than
+ *  being used as padding around the widget; set when packed, %TRUE by default.
+ * @pack: one of #GtkPackType indicating whether the child is packed with
+ *  reference to the start (top/left) or end (bottom/right) of the GtkBox.
+ * @is_secondary: %TRUE if the child is secondary
+ *
+ * The #GtkBoxChild holds a child widget of #GtkBox and describes how the child
+ * is to be packed into the #GtkBox. All fields of this #GtkBoxChild should be
+ * considered read-only and they should never be set directly by an application.
+ * Use gtk_box_query_child_packing() and gtk_box_set_child_packing() to query
+ * and set the #GtkBoxChild.padding, #GtkBoxChild.expand, #GtkBoxChild.fill and
+ * #GtkBoxChild.pack fields.
+ */
 struct _GtkBoxChild
 {
   GtkWidget *widget;