[gtk+] Docmentation improvements

[Matthias Clasen <matthiasc src gnome org>]

commit 294f810021cb318381074609246afad07e57f362
Author: Matthias Clasen <mclasen redhat com>
Date:   Tue Jun 15 01:23:30 2010 -0400

    Docmentation improvements
    
    Don't mention removed _defaults functions in the docs, also try
    to clarify the situation around fill and expand defaults.

 gtk/gtkbox.c |   51 +++++++++++++++++++++++++++++++++------------------
 1 files changed, 33 insertions(+), 18 deletions(-)
---
diff --git a/gtk/gtkbox.c b/gtk/gtkbox.c
index 3c56196..f16b7c4 100644
--- a/gtk/gtkbox.c
+++ b/gtk/gtkbox.c
@@ -54,15 +54,10 @@
  * 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.
+ * packed with the default values for #GtkBox:expand and #GtkBox:fill.
+ * 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.
@@ -229,30 +224,50 @@ gtk_box_class_init (GtkBoxClass *class)
 							 FALSE,
 							 GTK_PARAM_READWRITE));
 
+  /**
+   * GtkBox:expand:
+   *
+   * Whether the child should receive extra space when the parent grows.
+   *
+   * Note that the default value for this property is %FALSE for GtkBox,
+   * but #GtkHBox, #GtkVBox and other subclasses use the old default
+   * of %TRUE.
+   */
   gtk_container_class_install_child_property (container_class,
 					      CHILD_PROP_EXPAND,
-					      g_param_spec_boolean ("expand", 
-								    P_("Expand"), 
+					      g_param_spec_boolean ("expand",
+								    P_("Expand"),
 								    P_("Whether the child should receive extra space when the parent grows"),
-								    TRUE,
+								    FALSE,
 								    GTK_PARAM_READWRITE));
+
+  /**
+   * GtkBox:fill:
+   *
+   * Whether the child should receive extra space when the parent grows.
+   *
+   * Note that the default value for this property is %FALSE for GtkBox,
+   * but #GtkHBox, #GtkVBox and other subclasses use the old default
+   * of %TRUE.
+   */
   gtk_container_class_install_child_property (container_class,
 					      CHILD_PROP_FILL,
-					      g_param_spec_boolean ("fill", 
-								    P_("Fill"), 
+					      g_param_spec_boolean ("fill",
+								    P_("Fill"),
 								    P_("Whether extra space given to the child should be allocated to the child or used as padding"),
-								    TRUE,
+								    FALSE,
 								    GTK_PARAM_READWRITE));
+
   gtk_container_class_install_child_property (container_class,
 					      CHILD_PROP_PADDING,
-					      g_param_spec_uint ("padding", 
-								 P_("Padding"), 
+					      g_param_spec_uint ("padding",
+								 P_("Padding"),
 								 P_("Extra space to put between the child and its neighbors, in pixels"),
 								 0, G_MAXINT, 0,
 								 GTK_PARAM_READWRITE));
   gtk_container_class_install_child_property (container_class,
 					      CHILD_PROP_PACK_TYPE,
-					      g_param_spec_enum ("pack-type", 
+					      g_param_spec_enum ("pack-type",
 								 P_("Pack type"), 
 								 P_("A GtkPackType indicating whether the child is packed with reference to the start or end of the parent"),
 								 GTK_TYPE_PACK_TYPE, GTK_PACK_START,
@@ -736,8 +751,8 @@ gtk_box_get_child_property (GtkContainer *container,
 			    GValue       *value,
 			    GParamSpec   *pspec)
 {
-  gboolean expand = 0;
-  gboolean fill = 0;
+  gboolean expand = FALSE;
+  gboolean fill = FALSE;
   guint padding = 0;
   GtkPackType pack_type = 0;
   GList *list;