[gtk+] docs: Move documentation do inline comments: GtkContainer

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

commit c2ab54a31f9be01c1328babf794fd5bfa5ab098d
Author: Javier Jardón <jjardon gnome org>
Date:   Mon Oct 11 04:21:36 2010 +0200

    docs: Move documentation do inline comments: GtkContainer

 docs/reference/gtk/tmpl/.gitignore        |    1 +
 docs/reference/gtk/tmpl/gtkcontainer.sgml |  539 -----------------------------
 gtk/gtkcontainer.c                        |   84 +++++
 gtk/gtkcontainer.h                        |   10 +
 gtk/gtkwidget.c                           |    2 +-
 5 files changed, 96 insertions(+), 540 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/.gitignore b/docs/reference/gtk/tmpl/.gitignore
index f08a09e..3856389 100644
--- a/docs/reference/gtk/tmpl/.gitignore
+++ b/docs/reference/gtk/tmpl/.gitignore
@@ -9,6 +9,7 @@ gtkcalendar.sgml
 gtkcelleditable.sgml
 gtkcombobox.sgml
 gtkcomboboxentry.sgml
+gtkcontainer.sgml
 gtkeditable.sgml
 gtkentrybuffer.sgml
 gtkhbox.sgml
diff --git a/gtk/gtkcontainer.c b/gtk/gtkcontainer.c
index 055a2ea..845de34 100644
--- a/gtk/gtkcontainer.c
+++ b/gtk/gtkcontainer.c
@@ -44,6 +44,90 @@
 #include <gobject/gobjectnotifyqueue.c>
 #include <gobject/gvaluecollector.h>
 
+
+/**
+ * SECTION:gtkcontainer
+ * @Short_description: Base class for widgets which contain other widgets
+ * @Title: GtkContainer
+ *
+ * A GTK+ user interface is constructed by nesting widgets inside widgets.
+ * Container widgets are the inner nodes in the resulting tree of widgets:
+ * they contain other widgets. So, for example, you might have a #GtkWindow
+ * containing a #GtkFrame containing a #GtkLabel. If you wanted an image instead
+ * of a textual label inside the frame, you might replace the #GtkLabel widget
+ * with a #GtkImage widget.
+ *
+ * There are two major kinds of container widgets in GTK+. Both are subclasses
+ * of the abstract GtkContainer base class.
+ *
+ * The first type of container widget has a single child widget and derives
+ * from #GtkBin. These containers are <emphasis>decorators</emphasis>, which
+ * add some kind of functionality to the child. For example, a #GtkButton makes
+ * its child into a clickable button; a #GtkFrame draws a frame around its child
+ * and a #GtkWindow places its child widget inside a top-level window.
+ *
+ * The second type of container can have more than one child; its purpose is to
+ * manage <emphasis>layout</emphasis>. This means that these containers assign
+ * sizes and positions to their children. For example, a #GtkHBox arranges its
+ * children in a horizontal row, and a #GtkTable arranges the widgets it contains
+ * in a two-dimensional grid.
+ *
+ * GTK+ uses a height-for-width (and width-for-height) geometry management system.
+ * Height-for-width means that a widget can change how much vertical space it needs,
+ * depending on the amount of horizontal space that it is given (and similar for
+ * width-for-height).
+ * See <link linkend="geometry-management">GtkWidget's geometry management section</link>
+ * to learn more about height-for-width geometry management.
+ * <refsect2 id="child-properties">
+ * <title>Child properties</title>
+ * <para>
+ * GtkContainer introduces <emphasis>child properties</emphasis>.
+ * These are object properties that are not specific
+ * to either the container or the contained widget, but rather to their relation.
+ * Typical examples of child properties are the position or pack-type of a widget
+ * which is contained in a #GtkBox.
+ *
+ * Use gtk_container_class_install_child_property() to install child properties
+ * for a container class and gtk_container_class_find_child_property() or
+ * gtk_container_class_list_child_properties() to get information about existing
+ * child properties.
+ *
+ * To set the value of a child property, use gtk_container_child_set_property(),
+ * gtk_container_child_set() or gtk_container_child_set_valist().
+ * To obtain the value of a child property, use
+ * gtk_container_child_get_property(), gtk_container_child_get() or
+ * gtk_container_child_get_valist(). To emit notification about child property
+ * changes, use gtk_widget_child_notify().
+ * </para>
+ * </refsect2>
+ * <refsect2 id="GtkContainer-BUILDER-UI">
+ * <title>GtkContainer as GtkBuildable</title>
+ * <para>
+ * The GtkContainer implementation of the GtkBuildable interface
+ * supports a &lt;packing&gt; element for children, which can
+ * contain multiple &lt;property&gt; elements that specify
+ * child properties for the child.
+ * <example>
+ * <title>Child properties in UI definitions</title>
+ * <programlisting><![CDATA[
+ * <object class="GtkVBox">
+ *   <child>
+ *     <object class="GtkLabel"/>
+ *     <packing>
+ *       <property name="pack-type">start</property>
+ *     </packing>
+ *   </child>
+ * </object>
+ * ]]></programlisting>
+ * </example>
+ * Since 2.16, child properties can also be marked as translatable using
+ * the same "translatable", "comments" and "context" attributes that are used
+ * for regular properties.
+ * </para>
+ * </refsect2>
+ */
+
+
 struct _GtkContainerPrivate
 {
   GtkWidget *focus_child;
diff --git a/gtk/gtkcontainer.h b/gtk/gtkcontainer.h
index 8742911..607baf6 100644
--- a/gtk/gtkcontainer.h
+++ b/gtk/gtkcontainer.h
@@ -188,6 +188,16 @@ void	     gtk_container_child_get_property		(GtkContainer	   *container,
 							 const gchar	   *property_name,
 							 GValue		   *value);
 
+/**
+ * GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID:
+ * @object: the #GObject on which set_child_property() or get_child_property()
+ *  was called
+ * @property_id: the numeric id of the property
+ * @pspec: the #GParamSpec of the property
+ *
+ * This macro should be used to emit a standard warning about unexpected
+ * properties in set_child_property() and get_child_property() implementations.
+ */
 #define GTK_CONTAINER_WARN_INVALID_CHILD_PROPERTY_ID(object, property_id, pspec) \
     G_OBJECT_WARN_INVALID_PSPEC ((object), "child property id", (property_id), (pspec))
 
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 4ca6c4e..e3acd78 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -68,7 +68,7 @@
  * GtkWidget is the base class all widgets in GTK+ derive from. It manages the
  * widget lifecycle, states and style.
  *
- * <refsect2>
+ * <refsect2 id="geometry-management">
  * <title>Height-for-width Geometry Management</title>
  * <para>
  * GTK+ uses a height-for-width (and width-for-height) geometry management system.