documentation updates

svn path=/trunk/; revision=18303

7 files changed, 293 insertions, 196 deletions

diff --git a/ChangeLog b/ChangeLog
index 076b1cfba..440968f34 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2007-06-30  Matthias Clasen  <mclasen@redhat.com>
+
+	* gtk/gtkbuilder.c:
+	* gtk/gtkbuildable.c: Documentation updates.
+
 2007-06-29  Matthias Clasen  <mclasen@redhat.com>
 
 	* gdk/gdk.symbols:
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 51127fb1b..36265f125 100644
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,5 +1,11 @@
 2007-06-29  Matthias Clasen  <mclasen@redhat.com>
 
+	* gtk/tmpl/gtkbuilder.sgml:
+	* gtk/tmpl/gtkbuildable.sgml:
+	* gtk/tmpl/gtkuimanager.sgml: Updates
+
+2007-06-29  Matthias Clasen  <mclasen@redhat.com>
+
 	* gdk/gdk-sections.txt: Add gdk_keymap_have_bidi_layouts
 
 2007-06-29  Matthias Clasen  <mclasen@redhat.com>
diff --git a/docs/reference/gtk/tmpl/gtkbuildable.sgml b/docs/reference/gtk/tmpl/gtkbuildable.sgml
index 0778d003b..a140d7868 100644
--- a/docs/reference/gtk/tmpl/gtkbuildable.sgml
+++ b/docs/reference/gtk/tmpl/gtkbuildable.sgml
@@ -6,14 +6,23 @@ Interface for objects that can be built by GtkBuilder
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-In order to allow construction from a XML UI description,
-an object class must implement the #GtkBuildable interface.
-The interface includes method for setting names and properties
-of objects, parsing custom tags, constructing child objects.
+In order to allow construction from a <link linkend="BUILDER-UI">GtkBuilder 
+UI description</link>, an object class must implement the 
+GtkBuildable interface. The interface includes methods for setting 
+names and properties of objects, parsing custom tags, constructing 
+child objects.
+</para>
+<para>
+The GtkBuildable interface is implemented by all widgets and 
+many of the non-widget objects that are provided by GTK+. The
+main user of this interface is #GtkBuilder, there should be
+very little need for applications to call any 
+<function>gtk_buildable_...</function> functions.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 
+
 <!-- ##### SECTION Stability_Level ##### -->
 
 
@@ -25,28 +34,54 @@ of objects, parsing custom tags, constructing child objects.
 
 <!-- ##### STRUCT GtkBuildableIface ##### -->
 <para>
-The #GtkBuildableIface interface contains method that are
+The GtkBuildableIface interface contains method that are
 necessary to allow #GtkBuilder to construct an object from
-a XML UI description.
+a GtkBuilder UI definition.
 </para>
 
 @g_iface: the parent class
-@set_name: Stores the name attribute given in the XML UI description.
-  #GtkWidget maps this to the GtkWidget:name property, and 
+@set_name: Stores the name attribute given in the GtkBuilder UI definition.
+  #GtkWidget maps this to the #GtkWidget:name property, and 
   gtk_buildable_set_name() has a fallback implementation that stores
   the name as object data. Implement this method if your object
   has some notion of "name" and it makes sense to map the XML name
   attribute to it.
 @get_name: The getter corresponding to @set_name. Implement this
   if you implement @set_name.
-@add_child: 
-@set_buildable_property: 
-@construct_child: 
-@custom_tag_start: 
-@custom_tag_end: 
-@custom_finished: 
-@parser_finished: 
-@get_internal_child: 
+@add_child: Adds a child. The @type parameter can be used to 
+  differentiate the kind of child. #GtkContainer implements this 
+  to add add a child widget to the container, #GtkNotebook uses 
+  the @type to distinguish between page labels (of type "page-label") 
+  and normal children.
+@set_buildable_property: Sets a property of a buildable object.
+  It is normally not necessary to implement this, g_object_set_property()
+  is used by default. #GtkWindow implements this to delay showing itself
+  (i.e. setting the #GtkWidget:visible property) until the whole interface 
+  is created.
+@construct_child: Constructs a child of a buildable that has been
+  specified as "constructor" in the UI definition. #GtkUIManager implements 
+  this to reference to a widget created in a &lt;ui&gt; tag which is outside 
+  of the normal GtkBuilder UI definition hierarchy.
+@custom_tag_start: Implement this if the buildable needs to parse 
+  content below &lt;child&gt;. To handle an element, the implementation
+  must fill in the @parser structure and @user_data and return %TRUE.
+  #GtkWidget implements this to parse keyboard accelerators specified
+  in &lt;accelerator&gt; elements. #GtkContainer implements it to map 
+  properties defined via &lt;packing&gt; elements to child properties.
+  Note that @user_data must be freed in @custom_tag_end or @custom_finished.
+@custom_tag_end: Called for the end tag of each custom element that is
+  handled by the buildable (see @custom_tag_start).
+@custom_finished: Called for each custom tag handled by the buildable
+  when the builder finishes parsing (see @custom_tag_start)
+@parser_finished: Called when a builder finishes the parsing
+  of a UI definition. It is normally not necessary to implement this,
+  unless you need to perform special cleanup actions. #GtkWindow sets
+  the #GtkWidget:visible property here.
+@get_internal_child: Returns an internal child of a buildable. 
+  #GtkDialog implements this to give access to its @vbox, making
+  it possible to add children to the vbox in a UI definition.
+  Implement this if the buildable has internal children that may
+  need to be accessed from a UI definition.
 
 <!-- ##### FUNCTION gtk_buildable_set_name ##### -->
 <para>
diff --git a/docs/reference/gtk/tmpl/gtkbuilder.sgml b/docs/reference/gtk/tmpl/gtkbuilder.sgml
index 68d24df27..c9d99e445 100644
--- a/docs/reference/gtk/tmpl/gtkbuilder.sgml
+++ b/docs/reference/gtk/tmpl/gtkbuilder.sgml
@@ -2,26 +2,70 @@
 GtkBuilder
 
 <!-- ##### SECTION Short_Description ##### -->
-Build an interface from a UI definition description.
+Build an interface from an XML UI definition
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-This object represents an `instantiation' of an UI definition description. 
-When one of these objects is created, the XML file is read, and the 
-interface is created. The GtkBuilder object then provides an interface 
-for accessing the widgets in the interface by the names assigned to 
-them inside the UI description.
+A GtkBuilder is an auxiliary object that reads textual descriptions
+of a user interface and instantiates the described objects. 
+The functions gtk_builder_get_object() and gtk_builder_get_objects()
+can be used to access the widgets in the interface by the names assigned 
+to them inside the UI description. The function gtk_builder_connect_signals() 
+and variants thereof can be used to connect handlers to the named signals 
+in the description. 
+</para>
+<para>
+A GtkBuilder holds a reference to all objects that it has constructed
+and drops these references when it is finalized. To keep objects beyond
+the lifespan of the builder, they must be fetched with gtk_builder_get_object()
+and reffed with g_object_ref(). It is the responsibility of the user
+to destroy all toplevel windows that have been constructed by a builder
+(these are not automatically cleaned up when the builder is finalized, 
+since GTK+ itself holds a reference to each toplevel window).
+</para>
 
-The GtkBuilder object can also be used to connect handlers to the named 
-signals in the description. GtkBuilder also provides an interface by 
-which it can look up the signal handler names in the program's symbol 
-table and automatically connect as many handlers up as it can that way.
+<refsect2 id="BUILDER-UI"><title>GtkBuilder UI Definitions</title>
+<para>
+GtkBuilder parses textual descriptions of user interfaces which 
+are specified in an XML format which can be roughly described 
+by the following DTD.
+</para>
+<para>
+Do not confuse GtkBuilder UI Definitions with 
+<link linkend="XML-UI">GtkUIManager UI Definitions</link>, 
+which are more limited in scope. 
 </para>
+<para>
+<programlisting><![CDATA[
+<!ELEMENT interface object* >
+<!ELEMENT object    (property|signal|child|ANY)* >
+<!ELEMENT property  PCDATA >
+<!ELEMENT signal    EMPTY >
+<!ELEMENT child     (object|ANY*) >
 
-<!-- ##### SECTION See_Also ##### -->
+<!ATTLIST interface  domain         #IMPLIED >
+<!ATTLIST object     class          #REQUIRED
+                     id             #IMPLIED
+                     constructor    #IMPLIED >
+<!ATTLIST property   name           #REQUIRED
+                     translatable   #IMPLIED >
+<!ATTLIST signal     name           #REQUIRED
+                     handler        #REQUIRED
+                     after          #IMPLIED
+                     object         #IMPLIED >
+<!ATTLIST child      type           #IMPLIED
+                     internal-child #IMPLIED
+                     type-func      #IMPLIED >
+]]></programlisting>
+</para>
 <para>
-SEE ALSO
+Beyond this general structure, several object classes define
+their own XML DTD fragments for filling in the ANY placeholders.
 </para>
+</refsect2>
+
+<!-- ##### SECTION See_Also ##### -->
+
 
 <!-- ##### SECTION Stability_Level ##### -->
 
@@ -37,6 +81,19 @@ SEE ALSO
 
 </para>
 
+<!-- ##### STRUCT GtkBuilderClass ##### -->
+<para>
+
+</para>
+
+@get_type_from_name: Looks up a type by name. The default
+  implementation applies heuristics to map type names to
+  <function>_get_type</function> function names, e.g. 
+  GtkHBox to gtk_hbox_get_type(). This virtual function
+  is provided to allow language bindings to intercept the
+  type resolution process.
+
+
 <!-- ##### USER_FUNCTION GtkBuilderConnectFunc ##### -->
 <para>
 
@@ -153,9 +210,11 @@ SEE ALSO
 
 </para>
 
+@builder: 
 @pspec: 
 @string: 
 @value: 
+@error: 
 @Returns: 
 
 
@@ -164,9 +223,11 @@ SEE ALSO
 
 </para>
 
+@builder: 
 @type: 
 @string: 
 @value: 
+@error: 
 @Returns: 
 
 
diff --git a/docs/reference/gtk/tmpl/gtkuimanager.sgml b/docs/reference/gtk/tmpl/gtkuimanager.sgml
index 1bd22f2bc..26e53df76 100644
--- a/docs/reference/gtk/tmpl/gtkuimanager.sgml
+++ b/docs/reference/gtk/tmpl/gtkuimanager.sgml
@@ -14,40 +14,47 @@ action groups.
 <para>
 The UI definitions are specified in an XML format which can be
 roughly described by the following DTD. 
-<programlisting>
-&lt;!ELEMENT ui          (menubar|toolbar|popup|accelerator)* &gt;
-&lt;!ELEMENT menubar     (menuitem|separator|placeholder|menu)* &gt;
-&lt;!ELEMENT menu        (menuitem|separator|placeholder|menu)* &gt;
-&lt;!ELEMENT popup       (menuitem|separator|placeholder|menu)* &gt;
-&lt;!ELEMENT toolbar     (toolitem|separator|placeholder)* &gt;
-&lt;!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* &gt;
-&lt;!ELEMENT menuitem     EMPTY &gt;
-&lt;!ELEMENT toolitem     (menu?) &gt;
-&lt;!ELEMENT separator    EMPTY &gt;
-&lt;!ELEMENT accelerator  EMPTY &gt;
-&lt;!ATTLIST menubar      name                  &num;IMPLIED 
-                       action                &num;IMPLIED &gt;
-&lt;!ATTLIST toolbar      name                  &num;IMPLIED 
-                       action                &num;IMPLIED &gt;
-&lt;!ATTLIST popup        name                  &num;IMPLIED 
-                       action                &num;IMPLIED &gt;
-&lt;!ATTLIST placeholder  name                  &num;IMPLIED
-                       action                &num;IMPLIED &gt;
-&lt;!ATTLIST separator    name                  &num;IMPLIED
+</para>
+<para>
+Do not confuse the GtkUIManager UI Definitions described here with
+the similarly named <link linkend="BUILDER-UI">GtkBuilder UI 
+Definitions</link>. 
+</para>
+<para>
+<programlisting><![CDATA[
+<!ELEMENT ui          (menubar|toolbar|popup|accelerator)* >
+<!ELEMENT menubar     (menuitem|separator|placeholder|menu)* >
+<!ELEMENT menu        (menuitem|separator|placeholder|menu)* >
+<!ELEMENT popup       (menuitem|separator|placeholder|menu)* >
+<!ELEMENT toolbar     (toolitem|separator|placeholder)* >
+<!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* >
+<!ELEMENT menuitem     EMPTY >
+<!ELEMENT toolitem     (menu?) >
+<!ELEMENT separator    EMPTY >
+<!ELEMENT accelerator  EMPTY >
+<!ATTLIST menubar      name                  &num;IMPLIED 
+                       action                &num;IMPLIED >
+<!ATTLIST toolbar      name                  &num;IMPLIED 
+                       action                &num;IMPLIED >
+<!ATTLIST popup        name                  &num;IMPLIED 
+                       action                &num;IMPLIED >
+<!ATTLIST placeholder  name                  &num;IMPLIED
+                       action                &num;IMPLIED >
+<!ATTLIST separator    name                  &num;IMPLIED
                        action                &num;IMPLIED
-                       expand   (true|false) &num;IMPLIED &gt;
-&lt;!ATTLIST menu         name                  &num;IMPLIED
+                       expand   (true|false) &num;IMPLIED >
+<!ATTLIST menu         name                  &num;IMPLIED
                        action                &num;REQUIRED
-                       position (top|bot)    &num;IMPLIED &gt;
-&lt;!ATTLIST menuitem     name                  &num;IMPLIED
+                       position (top|bot)    &num;IMPLIED >
+<!ATTLIST menuitem     name                  &num;IMPLIED
                        action                &num;REQUIRED
-                       position (top|bot)    &num;IMPLIED &gt;
-&lt;!ATTLIST toolitem     name                  &num;IMPLIED
+                       position (top|bot)    &num;IMPLIED >
+<!ATTLIST toolitem     name                  &num;IMPLIED
                        action                &num;REQUIRED
-                       position (top|bot)    &num;IMPLIED &gt;
-&lt;!ATTLIST accelerator  name                  &num;IMPLIED
-                       action                &num;REQUIRED &gt;
-</programlisting>
+                       position (top|bot)    &num;IMPLIED >
+<!ATTLIST accelerator  name                  &num;IMPLIED
+                       action                &num;REQUIRED >
+]]></programlisting>
 There are some additional restrictions beyond those specified in the
 DTD, e.g. every toolitem must have a toolbar in its anchestry and
 every menuitem must have a menubar or popup in its anchestry. Since
@@ -194,7 +201,7 @@ to which the submenu is associated.
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GtkBuilder
 </para>
 
 <!-- ##### SECTION Stability_Level ##### -->
diff --git a/gtk/gtkbuildable.c b/gtk/gtkbuildable.c
index e5dbf5699..d1748f65e 100644
--- a/gtk/gtkbuildable.c
+++ b/gtk/gtkbuildable.c
@@ -44,10 +44,7 @@ gtk_buildable_get_type (void)
  * @buildable: a #GtkBuildable
  * @name: name to set
  *
- * Sets the name of the buildable object, it's used to synchronize the name
- * if the object already has it's own concept of name.
- *
- * #GtkWidget implements this to map the buildable name to the widget name
+ * Sets the name of the @buildable object.
  *
  * Since: 2.12
  **/
@@ -75,12 +72,11 @@ gtk_buildable_set_name (GtkBuildable *buildable,
  * gtk_buildable_get_name:
  * @buildable: a #GtkBuildable
  *
- *   
- * Returns the buildable name. #GtkBuilder sets the name based on the 
- * the <link linkend="BUILDER-UI">GtkBuilder UI definition</link> used 
- * to construct the @buildable.
- *
- * #GtkWidget implements this to map the buildable name to the widget name
+ * Gets the name of the @buildable object. 
+ * 
+ * #GtkBuilder sets the name based on the the 
+ * <link linkend="BUILDER-UI">GtkBuilder UI definition</link> 
+ * used to construct the @buildable.
  *
  * Returns: the name set with gtk_buildable_set_name()
  *
@@ -109,13 +105,9 @@ gtk_buildable_get_name (GtkBuildable *buildable)
  * @child: child to add
  * @type: kind of child or %NULL
  *
- * Add a child to a buildable. type is an optional string
+ * Adds a child to @buildable. @type is an optional string
  * describing how the child should be added.
  *
- * #GtkContainer implements this to be able to add a child widget
- * to the container. #GtkNotebook uses the @type to distinguish between
- * page labels (@type = "page-label") and normal children.
- *
  * Since: 2.12
  **/
 void
@@ -142,14 +134,7 @@ gtk_buildable_add_child (GtkBuildable *buildable,
  * @name: name of property
  * @value: value of property
  *
- * Sets the property name @name to @value on the buildable object @buildable
- * which is created by the @builder.
- *
- * This is optional to implement and is normally not needed.
- * g_object_set_property() is used as a fallback.
- *
- * #GtkWindow implements this to delay showing (::visible) itself until
- * the whole interface is fully created.
+ * Sets the property name @name to @value on the @buildable object.
  *
  * Since: 2.12
  **/
@@ -178,12 +163,11 @@ gtk_buildable_set_buildable_property (GtkBuildable *buildable,
  * @buildable: a #GtkBuildable
  * @builder: a #GtkBuilder
  *
- * Finish the parsing of a <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
- * snippet. Note that this will be called once for each time gtk_builder_add_from_file or
- * gtk_builder_add_from_string is called on a builder.
- *
- * #GtkWindow implements this to delay showing (::visible) itself until
- * the whole interface is fully created.
+ * Called when the builder finishes the parsing of a 
+ * <link linkend="BUILDER-UI">GtkBuilder UI definition</link>. 
+ * Note that this will be called once for each time 
+ * gtk_builder_add_from_file() or gtk_builder_add_from_string() 
+ * is called on a builder.
  *
  * Since: 2.12
  **/
@@ -202,19 +186,17 @@ gtk_buildable_parser_finished (GtkBuildable *buildable,
 }
 
 /**
- * gtk_buildable_construct_child
+ * gtk_buildable_construct_child:
  * @buildable: A #GtkBuildable
  * @builder: #GtkBuilder used to construct this object
  * @name: name of child to construct
  *
- * Construct a child of @buildable with the name @name.
+ * Constructs a child of @buildable with the name @name. 
  *
- * #GtkUIManager implements this to reference to a widget created in a 
- * &lt;ui&gt; tag which is outside of the normal 
- * <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
- * hierarchy.
+ * #GtkBuilder calls this function if a "constructor" has been
+ * specified in the UI definition.
  *
- * Returns: the child with name @name
+ * Returns: the constructed child
  *
  * Since: 2.12
  **/
@@ -236,27 +218,17 @@ gtk_buildable_construct_child (GtkBuildable *buildable,
 }
 
 /**
- * gtk_buildable_custom_tag_start
+ * gtk_buildable_custom_tag_start:
  * @buildable: a #GtkBuildable
  * @builder: a #GtkBuilder used to construct this object
  * @child: child object or %NULL for non-child tags
  * @tagname: name of tag
- * @parser: a #GMarkupParser structure
- * @data: user data that will be passed in to parser functions
+ * @parser: a #GMarkupParser structure to fill in
+ * @data: return location for user data that will be passed in 
+ *   to parser functions
  *
- * This is called when an unknown tag under &lt;child&gt; tag is found.
+ * This is called for each unknown element under &lt;child&gt;.
  * 
- * Called when an unknown tag is present under a &lt;child&gt; tag.
- * If the buildable implementation wishes to handle the tag it should
- * return %TRUE and fill in the @parser structure. Remember to either
- * implement custom_tag_end or custom_tag_finish to free
- * the user data allocated here.
- *
- * #GtkWidget implements this and parsers all &lt;accelerator&gt; tags to
- * keyboard accelerators.
- * #GtkContainer implements this to map properties defined under
- * &lt;packing&gt; tag to child properties.
- *
  * Returns: %TRUE if a object has a custom implementation, %FALSE
  *          if it doesn't.
  *
@@ -284,15 +256,15 @@ gtk_buildable_custom_tag_start (GtkBuildable  *buildable,
 }
 
 /**
- * gtk_buildable_custom_tag_end
+ * gtk_buildable_custom_tag_end:
  * @buildable: A #GtkBuildable
  * @builder: #GtkBuilder used to construct this object
  * @child: child object or %NULL for non-child tags
  * @tagname: name of tag
  * @data: user data that will be passed in to parser functions
  *
- * This is called for each custom tag handled by the buildable.
- * It will be called when the end of the tag is reached.
+ * This is called at the end of each custom element handled by 
+ * the buildable.
  *
  * Since: 2.12
  **/
@@ -345,7 +317,7 @@ gtk_buildable_custom_finished (GtkBuildable  *buildable,
 }
 
 /**
- * gtk_buildable_get_internal_child
+ * gtk_buildable_get_internal_child:
  * @buildable: a #GtkBuildable
  * @builder: a #GtkBuilder
  * @childname: name of child
diff --git a/gtk/gtkbuilder.c b/gtk/gtkbuilder.c
index de4e43a3a..03f28817e 100644
--- a/gtk/gtkbuilder.c
+++ b/gtk/gtkbuilder.c
@@ -47,9 +47,10 @@ static void gtk_builder_get_property   (GObject         *object,
                                         guint            prop_id,
                                         GValue          *value,
                                         GParamSpec      *pspec);
-static GType gtk_builder_real_get_type_from_name   (GtkBuilder      *builder,
-                                                    const char      *type_name);
-static gint _gtk_builder_enum_from_string (GType type, const char *string);
+static GType gtk_builder_real_get_type_from_name (GtkBuilder  *builder,
+                                                  const gchar *type_name);
+static gint _gtk_builder_enum_from_string        (GType        type, 
+                                                  const gchar *string);
 
 
 enum {
@@ -82,6 +83,16 @@ gtk_builder_class_init (GtkBuilderClass *klass)
 
   klass->get_type_from_name = gtk_builder_real_get_type_from_name;
 
+ /** 
+  * GtkBuilder:translation-domain:
+  *
+  * The translation domain used when translating property values that
+  * have been marked as translatable in interface descriptions.
+  * If the translation domain is %NULL, #GtkBuilder uses gettext(),
+  * otherwise dgettext().
+  *
+  * Since: 2.12
+  */
   g_object_class_install_property (gobject_class,
                                    PROP_TRANSLATION_DOMAIN,
                                    g_param_spec_string ("translation-domain",
@@ -218,7 +229,8 @@ _gtk_builder_resolve_type_lazily (const gchar *name)
  */
 
 static GType
-gtk_builder_real_get_type_from_name (GtkBuilder *builder, const char *type_name)
+gtk_builder_real_get_type_from_name (GtkBuilder  *builder, 
+                                     const gchar *type_name)
 {
   GType gtype;
 
@@ -280,8 +292,8 @@ gtk_builder_get_parameters (GtkBuilder  *builder,
               object = gtk_builder_get_object (builder, prop->data);
               if (!object)
                 {
-                  g_warning ("failed to get constuct only property %s of %s "
-                             "with value `%s'",
+                  g_warning ("Failed to get constuct only property "
+                             "%s of %s with value `%s'",
                              prop->name, object_name, prop->data);
                   continue;
                 }
@@ -308,7 +320,7 @@ gtk_builder_get_parameters (GtkBuilder  *builder,
       else if (!gtk_builder_value_from_string (builder, pspec,
 					       prop->data, &parameter.value, &error))
         {
-          g_warning ("failed to set property %s.%s to %s: %s",
+          g_warning ("Failed to set property %s.%s to %s: %s",
                      g_type_name (object_type), prop->name, prop->data,
 		     error->message);
 	  g_error_free (error);
@@ -590,7 +602,7 @@ _gtk_builder_finish (GtkBuilder  *builder)
  *
  * Creates a new builder object.
  *
- * Return value: a new builder object.
+ * Return value: a new #GtkBuilder object
  *
  * Since: 2.12
  **/
@@ -604,10 +616,10 @@ gtk_builder_new (void)
  * gtk_builder_add_from_file:
  * @builder: a #GtkBuilder
  * @filename: the name of the file to parse
- * @error: return location for an error
+ * @error: return location for an error, or %NULL
  *
- * Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder UI definition</link> and 
- * merges it with the current contents of @builder. 
+ * Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder 
+ * UI definition</link> and merges it with the current contents of @builder. 
  * 
  * Returns: A positive value on success, 0 if an error occurred
  *
@@ -618,7 +630,7 @@ gtk_builder_add_from_file (GtkBuilder   *builder,
                            const gchar  *filename,
                            GError      **error)
 {
-  char *buffer;
+  gchar *buffer;
   gsize length;
   GError *tmp_error;
 
@@ -653,10 +665,10 @@ gtk_builder_add_from_file (GtkBuilder   *builder,
  * @builder: a #GtkBuilder
  * @buffer: the string to parse
  * @length: the length of @buffer (may be -1 if @buffer is nul-terminated)
- * @error: return location for an error
+ * @error: return location for an error, or %NULL
  *
- * Parses a file containing a <link linkend="BUILDER-UI">GtkBuilder UI definition</link> and 
- * merges it with the current contents of @builder. 
+ * Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder 
+ * UI definition</link> and merges it with the current contents of @builder. 
  * 
  * Returns: A positive value on success, 0 if an error occurred
  *
@@ -692,10 +704,11 @@ gtk_builder_add_from_string (GtkBuilder   *builder,
  * @builder: a #GtkBuilder
  * @name: name of object to get
  *
- * Gets the object named @name.
+ * Gets the object named @name. Note that this function does not
+ * increment the reference count of the returned object. 
  *
  * Return value: the object named @name or %NULL if it could not be 
- *    found in the object tree
+ *    found in the object tree. 
  *
  * Since: 2.12
  **/
@@ -710,9 +723,9 @@ gtk_builder_get_object (GtkBuilder  *builder,
 }
 
 static void
-object_add_to_list (gchar *object_id,
-                    GObject *object,
-                    GSList **list)
+object_add_to_list (gchar    *object_id,
+                    GObject  *object,
+                    GSList  **list)
 {
   *list = g_slist_prepend (*list, object);
 }
@@ -721,10 +734,13 @@ object_add_to_list (gchar *object_id,
  * gtk_builder_get_objects:
  * @builder: a #GtkBuilder
  *
- * Gets all objects that have been constructed by @builder.
+ * Gets all objects that have been constructed by @builder. Note that 
+ * this function does not increment the reference counts of the returned
+ * objects.
  *
  * Return value: a newly-allocated #GSList containing all the objects
- *   constructed by the #GtkBuilder instance
+ *   constructed by the #GtkBuilder instance. It should be freed by
+ *   g_slist_free()
  *
  * Since: 2.12
  **/
@@ -745,10 +761,8 @@ gtk_builder_get_objects (GtkBuilder *builder)
  * @builder: a #GtkBuilder
  * @domain: the translation domain or %NULL
  *
- * Sets the translation domain and uses dgettext() for translating the
- * property values marked as translatable from an interface description.
- * You can also pass in %NULL to this method to use gettext() instead of
- * dgettext().
+ * Sets the translation domain of @builder. 
+ * See #GtkBuilder:translation-domain.
  *
  * Since: 2.12
  **/
@@ -771,7 +785,7 @@ gtk_builder_set_translation_domain (GtkBuilder  *builder,
  * gtk_builder_get_translation_domain:
  * @builder: a #GtkBuilder
  *
- * Gets the translation domain.
+ * Gets the translation domain of @builder.
  *
  * Return value: the translation domain. This string is owned
  * by the builder object and must not be modified or freed.
@@ -805,7 +819,7 @@ gtk_builder_connect_signals_default (GtkBuilder    *builder,
   
   if (!g_module_symbol (args->module, handler_name, (gpointer)&func))
     {
-      g_warning ("could not find signal handler '%s'", handler_name);
+      g_warning ("Could not find signal handler '%s'", handler_name);
       return;
     }
 
@@ -822,8 +836,8 @@ gtk_builder_connect_signals_default (GtkBuilder    *builder,
  * @user_data: a pointer to a structure sent in as user data to all signals
  *
  * This method is a simpler variation of gtk_builder_connect_signals_full().
- * It uses #GModule's introspective features (by opening the module %NULL) to
- * look at the application's symbol table.  From here it tries to match
+ * It uses #GModule's introspective features (by opening the module %NULL) 
+ * to look at the application's symbol table. From here it tries to match
  * the signal handler names given in the interface description with
  * symbols in the application and connects the signals.
  * 
@@ -841,7 +855,7 @@ gtk_builder_connect_signals (GtkBuilder *builder,
   g_return_if_fail (GTK_IS_BUILDER (builder));
   
   if (!g_module_supported ())
-    g_error ("gtk_builder_connect_signals requires working GModule");
+    g_error ("gtk_builder_connect_signals() requires working GModule");
 
   args = g_slice_new0 (connect_args);
   args->module = g_module_open (NULL, G_MODULE_BIND_LAZY);
@@ -858,10 +872,10 @@ gtk_builder_connect_signals (GtkBuilder *builder,
 /**
  * GtkBuilderConnectFunc:
  * @builder: a #GtkBuilder
- * @object: a GObject subclass to connect a signal to
+ * @object: object to connect a signal to
  * @signal_name: name of the signal
  * @handler_name: name of the handler
- * @connect_object: GObject, if non-%NULL, use g_signal_connect_object.
+ * @connect_object: a #GObject, if non-%NULL, use g_signal_connect_object()
  * @flags: #GConnectFlags to use
  * @user_data: user data
  *
@@ -877,12 +891,12 @@ gtk_builder_connect_signals (GtkBuilder *builder,
 /**
  * gtk_builder_connect_signals_full:
  * @builder: a #GtkBuilder
- * @func: the function used to connect the signals.
- * @user_data: arbitrary data that will be passed to the connection function.
+ * @func: the function used to connect the signals
+ * @user_data: arbitrary data that will be passed to the connection function
  *
  * This function can be thought of the interpreted language binding
- * version of gtk_builder_signal_autoconnect(), except that it does not
- * require gmodule to function correctly.
+ * version of gtk_builder_connect_signals(), except that it does not
+ * require GModule to function correctly.
  *
  * Since: 2.12
  */
@@ -920,7 +934,7 @@ gtk_builder_connect_signals_full (GtkBuilder            *builder,
 	  connect_object = g_hash_table_lookup (builder->priv->objects,
 						signal->connect_object_name);
 	  if (!connect_object)
-	      g_warning ("could not lookup object %s on signal %s of object %s",
+	      g_warning ("Could not lookup object %s on signal %s of object %s",
 			 signal->connect_object_name, signal->name,
 			 signal->object_name);
 	}
@@ -935,23 +949,23 @@ gtk_builder_connect_signals_full (GtkBuilder            *builder,
 }
 
 /**
- * gtk_builder_value_from_string
+ * gtk_builder_value_from_string:
  * @builder: a #GtkBuilder
- * @pspec: the GParamSpec for the property
- * @string: the string representation of the value.
- * @value: the GValue to store the result in.
- * @error: return location for an error
+ * @pspec: the #GParamSpec for the property
+ * @string: the string representation of the value
+ * @value: the #GValue to store the result in
+ * @error: return location for an error, or %NULL
  *
- * This function demarshals a value from a string.  This function
+ * This function demarshals a value from a string. This function
  * calls g_value_init() on the @value argument, so it need not be
  * initialised beforehand.
  *
  * This function can handle char, uchar, boolean, int, uint, long,
- * ulong, enum, flags, float, double, string, GdkColor and
- * GtkAdjustment type values.  Support for GtkWidget type values is
+ * ulong, enum, flags, float, double, string, #GdkColor and
+ * #GtkAdjustment type values. Support for #GtkWidget type values is
  * still to come.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  *
  * Since: 2.12
  */
@@ -982,16 +996,19 @@ gtk_builder_value_from_string (GtkBuilder   *builder,
 }
 
 /**
- * gtk_builder_value_from_string_type
+ * gtk_builder_value_from_string_type:
  * @builder: a #GtkBuilder
- * @type: the GType of the value
- * @string: the string representation of the value.
- * @value: the GValue to store the result in.
- * @error: return location for an error
+ * @type: the #GType of the value
+ * @string: the string representation of the value
+ * @value: the #GValue to store the result in
+ * @error: return location for an error, or %NULL
  *
- * Like gtk_builder_value_from_string(), but takes a #GType instead of #GParamSpec.
+ * Like gtk_builder_value_from_string(), this function demarshals 
+ * a value from a string, but takes a #GType instead of #GParamSpec.
+ * This function calls g_value_init() on the @value argument, so it 
+ * need not be initialised beforehand.
  *
- * Returns: %TRUE on success.
+ * Returns: %TRUE on success
  *
  * Since: 2.12
  */
@@ -1041,7 +1058,7 @@ gtk_builder_value_from_string_type (GtkBuilder   *builder,
 		  g_set_error (error,
 			       GTK_BUILDER_ERROR,
 			       GTK_BUILDER_ERROR_INVALID_VALUE,
-			       "could not parse int `%s'",
+			       "Could not parse boolean `%s'",
 			       string);
                   ret = FALSE;
                   break;
@@ -1064,7 +1081,7 @@ gtk_builder_value_from_string_type (GtkBuilder   *builder,
 	    g_set_error (error,
 			 GTK_BUILDER_ERROR,
 			 GTK_BUILDER_ERROR_INVALID_VALUE,
-			 "could not parse long `%s'",
+			 "Could not parse integer `%s'",
 			 string);
             ret = FALSE;
             break;
@@ -1087,7 +1104,7 @@ gtk_builder_value_from_string_type (GtkBuilder   *builder,
 	    g_set_error (error,
 			 GTK_BUILDER_ERROR,
 			 GTK_BUILDER_ERROR_INVALID_VALUE,
-			 "could not parse ulong `%s'",
+			 "Could not parse unsigned integer `%s'",
 			 string);
             ret = FALSE;
             break;
@@ -1107,7 +1124,7 @@ gtk_builder_value_from_string_type (GtkBuilder   *builder,
     case G_TYPE_FLOAT:
     case G_TYPE_DOUBLE:
       {
-        double d;
+        gdouble d;
         gchar *endptr;
         errno = 0;
         d = g_ascii_strtod (string, &endptr);
@@ -1116,7 +1133,7 @@ gtk_builder_value_from_string_type (GtkBuilder   *builder,
 	    g_set_error (error,
 			 GTK_BUILDER_ERROR,
 			 GTK_BUILDER_ERROR_INVALID_VALUE,
-			 "could not parse double `%s'",
+			 "Could not parse double `%s'",
 			 string);
             ret = FALSE;
             break;
@@ -1144,14 +1161,14 @@ gtk_builder_value_from_string_type (GtkBuilder   *builder,
 	      g_set_error (error,
 			   GTK_BUILDER_ERROR,
 			   GTK_BUILDER_ERROR_INVALID_VALUE,
-			   "could not parse color `%s'",
+			   "Could not parse color `%s'",
 			   string);
               ret = FALSE;
             }
         }
       else if (G_VALUE_HOLDS (value, G_TYPE_STRV))
         {
-          char **vector = g_strsplit (string, "\n", 0);
+          gchar **vector = g_strsplit (string, "\n", 0);
           g_value_take_boxed (value, vector);
         }
       else
@@ -1186,13 +1203,13 @@ gtk_builder_value_from_string_type (GtkBuilder   *builder,
       }
         else
 #endif
-          ret = FALSE;
+        ret = FALSE;
       break;
     default:
       g_set_error (error,
 		   GTK_BUILDER_ERROR,
 		   GTK_BUILDER_ERROR_INVALID_VALUE,
-		   "unsupported GType `%s'",
+		   "Unsupported GType `%s'",
 		   g_type_name (type));
       ret = FALSE;
       break;
@@ -1202,7 +1219,8 @@ gtk_builder_value_from_string_type (GtkBuilder   *builder,
 }
 
 static gint
-_gtk_builder_enum_from_string (GType type, const char *string)
+_gtk_builder_enum_from_string (GType        type, 
+                               const gchar *string)
 {
   GEnumClass *eclass;
   GEnumValue *ev;
@@ -1230,14 +1248,15 @@ _gtk_builder_enum_from_string (GType type, const char *string)
 }
 
 guint
-_gtk_builder_flags_from_string (GType type, const char *string)
+_gtk_builder_flags_from_string (GType        type, 
+                                const gchar *string)
 {
   GFlagsClass *fclass;
   gchar *endptr, *prevptr;
   guint i, j, ret;
-  char *flagstr;
+  gchar *flagstr;
   GFlagsValue *fv;
-  const char  *flag;
+  const gchar *flag;
   gunichar ch;
   gboolean eos;
 
@@ -1314,18 +1333,19 @@ _gtk_builder_flags_from_string (GType type, const char *string)
 /**
  * gtk_builder_get_type_from_name:
  * @builder: a #GtkBuilder
- * @type_name: Type name to lookup
+ * @type_name: type name to lookup
  *
- * This method is used to lookup a type. It can be implemented in a 
- * subclass to override the #GType of an object created by the builder.
+ * Looks up a type by name, using the virtual function that 
+ * #GtkBuilder has for that purpose.
  *
- * Returns: the #GType found for @type_name or #G_TYPE_INVALID if no
- *   type was found
+ * Returns: the #GType found for @type_name or #G_TYPE_INVALID 
+ *   if no type was found
  *
  * Since 2.12
  */
 GType
-gtk_builder_get_type_from_name (GtkBuilder *builder, const gchar *type_name)
+gtk_builder_get_type_from_name (GtkBuilder  *builder, 
+                                const gchar *type_name)
 {
   g_return_val_if_fail (GTK_IS_BUILDER (builder), G_TYPE_INVALID);
   g_return_val_if_fail (type_name != NULL, G_TYPE_INVALID);
@@ -1333,15 +1353,6 @@ gtk_builder_get_type_from_name (GtkBuilder *builder, const gchar *type_name)
   return GTK_BUILDER_GET_CLASS (builder)->get_type_from_name (builder, type_name);
 }
 
-/**
- * gtk_builder_error_quark:
- *
- * Registers an error quark for #GtkBuilder if necessary.
- * 
- * Return value: The error quark used for #GtkBuilder errors.
- *
- * Since: 2.12
- **/
 GQuark
 gtk_builder_error_quark (void)
 {