add new "is_important" property

Fri Aug  1 15:26:46 2003  Soeren Sandmann  <sandmann@daimi.au.dk>

	* gtk/gtktoolbar.c, gtk/toolitem.c: add new "is_important"
	property

	* gtk/gtkradiotoolbutton.c
	(gtk_radio_tool_button_new_from_widget): Don't take a stock id

	* gtk/gtkradiotoolbutton.c
	(gtk_radio_tool_button_new_with_stock_from_widget): make this
	function take a stock_id.

	* gtk/toolbar: documentation

21 files changed, 1192 insertions, 86 deletions

diff --git a/ChangeLog b/ChangeLog
index d0357e1f31..8c5919c934 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+Fri Aug  1 15:26:46 2003  Soeren Sandmann  <sandmann@daimi.au.dk>
+
+	* gtk/gtktoolbar.c, gtk/toolitem.c: add new "is_important"
+	property
+	
+	* gtk/gtkradiotoolbutton.c
+	(gtk_radio_tool_button_new_from_widget): Don't take a stock id
+
+	* gtk/gtkradiotoolbutton.c
+	(gtk_radio_tool_button_new_with_stock_from_widget): make this
+	function take a stock_id.
+
+	* gtk/toolbar: documentation
+
 Mon Aug  4 14:53:46 2003  Owen Taylor  <otaylor@redhat.com>
 
 	* gdk/x11/gdkimage-x11.c (_gdk_windowing_image_init): 
diff --git a/ChangeLog.pre-2-10 b/ChangeLog.pre-2-10
index d0357e1f31..8c5919c934 100644
--- a/ChangeLog.pre-2-10
+++ b/ChangeLog.pre-2-10
@@ -1,3 +1,17 @@
+Fri Aug  1 15:26:46 2003  Soeren Sandmann  <sandmann@daimi.au.dk>
+
+	* gtk/gtktoolbar.c, gtk/toolitem.c: add new "is_important"
+	property
+	
+	* gtk/gtkradiotoolbutton.c
+	(gtk_radio_tool_button_new_from_widget): Don't take a stock id
+
+	* gtk/gtkradiotoolbutton.c
+	(gtk_radio_tool_button_new_with_stock_from_widget): make this
+	function take a stock_id.
+
+	* gtk/toolbar: documentation
+
 Mon Aug  4 14:53:46 2003  Owen Taylor  <otaylor@redhat.com>
 
 	* gdk/x11/gdkimage-x11.c (_gdk_windowing_image_init): 
diff --git a/ChangeLog.pre-2-4 b/ChangeLog.pre-2-4
index d0357e1f31..8c5919c934 100644
--- a/ChangeLog.pre-2-4
+++ b/ChangeLog.pre-2-4
@@ -1,3 +1,17 @@
+Fri Aug  1 15:26:46 2003  Soeren Sandmann  <sandmann@daimi.au.dk>
+
+	* gtk/gtktoolbar.c, gtk/toolitem.c: add new "is_important"
+	property
+	
+	* gtk/gtkradiotoolbutton.c
+	(gtk_radio_tool_button_new_from_widget): Don't take a stock id
+
+	* gtk/gtkradiotoolbutton.c
+	(gtk_radio_tool_button_new_with_stock_from_widget): make this
+	function take a stock_id.
+
+	* gtk/toolbar: documentation
+
 Mon Aug  4 14:53:46 2003  Owen Taylor  <otaylor@redhat.com>
 
 	* gdk/x11/gdkimage-x11.c (_gdk_windowing_image_init): 
diff --git a/ChangeLog.pre-2-6 b/ChangeLog.pre-2-6
index d0357e1f31..8c5919c934 100644
--- a/ChangeLog.pre-2-6
+++ b/ChangeLog.pre-2-6
@@ -1,3 +1,17 @@
+Fri Aug  1 15:26:46 2003  Soeren Sandmann  <sandmann@daimi.au.dk>
+
+	* gtk/gtktoolbar.c, gtk/toolitem.c: add new "is_important"
+	property
+	
+	* gtk/gtkradiotoolbutton.c
+	(gtk_radio_tool_button_new_from_widget): Don't take a stock id
+
+	* gtk/gtkradiotoolbutton.c
+	(gtk_radio_tool_button_new_with_stock_from_widget): make this
+	function take a stock_id.
+
+	* gtk/toolbar: documentation
+
 Mon Aug  4 14:53:46 2003  Owen Taylor  <otaylor@redhat.com>
 
 	* gdk/x11/gdkimage-x11.c (_gdk_windowing_image_init): 
diff --git a/ChangeLog.pre-2-8 b/ChangeLog.pre-2-8
index d0357e1f31..8c5919c934 100644
--- a/ChangeLog.pre-2-8
+++ b/ChangeLog.pre-2-8
@@ -1,3 +1,17 @@
+Fri Aug  1 15:26:46 2003  Soeren Sandmann  <sandmann@daimi.au.dk>
+
+	* gtk/gtktoolbar.c, gtk/toolitem.c: add new "is_important"
+	property
+	
+	* gtk/gtkradiotoolbutton.c
+	(gtk_radio_tool_button_new_from_widget): Don't take a stock id
+
+	* gtk/gtkradiotoolbutton.c
+	(gtk_radio_tool_button_new_with_stock_from_widget): make this
+	function take a stock_id.
+
+	* gtk/toolbar: documentation
+
 Mon Aug  4 14:53:46 2003  Owen Taylor  <otaylor@redhat.com>
 
 	* gdk/x11/gdkimage-x11.c (_gdk_windowing_image_init): 
diff --git a/docs/reference/gtk/tmpl/gtkradiotoolbutton.sgml b/docs/reference/gtk/tmpl/gtkradiotoolbutton.sgml
index fe78970cc5..824f13d450 100644
--- a/docs/reference/gtk/tmpl/gtkradiotoolbutton.sgml
+++ b/docs/reference/gtk/tmpl/gtkradiotoolbutton.sgml
@@ -2,21 +2,63 @@
 GtkRadioToolButton
 
 <!-- ##### SECTION Short_Description ##### -->
-
+A toolbar item that contains a radio button.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+A #GtkRadioToolButton is a #GtkToolItem that contains a radio button,
+that is, a button that is part of a group of toggle buttons where only
+one button can be active at a time.
+</para>
 
+<para>
+Use gtk_radio_tool_button_new() to create a new
+#GtkRadioToolButton. use gtk_radio_tool_button_new_from_widget() to
+create a new #GtkRadioToolButton that is part of the same group as an
+existing #GtkRadioToolButton. Use
+gtk_radio_tool_button_new_from_stock() or
+gtk_radio_tool_button_new_from_widget_with_stock() to create a new
+#GtkRAdioToolButton containing a stock item.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
+<variablelist>
+
+<varlistentry>
+<term>#GtkToolbar</term>
+<listitem><para>The toolbar widget</para></listitem>
+</varlistentry>
+
+<varlistentry>
+  <term>#GtkToolButton</term>
+  <listitem><para>
+      An ancestor class of GtkRadioToolButton. The properties
+      "label_widget", "label", "icon_widget", and "stock_id" on
+      #GtkToolButton determine the label and icon used on a
+      #GtkRadioToolButton.
+  </para></listitem>
+</varlistentry>
+
+<varlistentry>
+  <term>#GtkSeparatorToolItem</term>
+  <listitem>
+    <para>A subclass of #GtkToolItem that separates groups of
+      items on a toolbar. It is usually a good idea to put a separator
+      before and after a group of #GtkRadioToolButtons on a #GtkToolbar.
+    </para>
+  </listitem>
+</varlistentry>
+
+</variablelist>
+
 </para>
 
 <!-- ##### STRUCT GtkRadioToolButton ##### -->
 <para>
-
+  The #GtkRadioToolButton contains only private data and should only
+  be accessed through the functions described below.
 </para>
 
 
@@ -45,7 +87,6 @@ GtkRadioToolButton
 </para>
 
 @group: 
-@stock_id: 
 @Returns: 
 
 
@@ -55,6 +96,7 @@ GtkRadioToolButton
 </para>
 
 @group: 
+@stock_id: 
 @Returns: 
 
 
diff --git a/docs/reference/gtk/tmpl/gtkseparatortoolitem.sgml b/docs/reference/gtk/tmpl/gtkseparatortoolitem.sgml
index 1271d6f302..167d49e474 100644
--- a/docs/reference/gtk/tmpl/gtkseparatortoolitem.sgml
+++ b/docs/reference/gtk/tmpl/gtkseparatortoolitem.sgml
@@ -2,21 +2,37 @@
 GtkSeparatorToolItem
 
 <!-- ##### SECTION Short_Description ##### -->
-
+A toolbar item that separates groups of other toolbar items.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+  A #GtkSeparatorItem is a #GtkToolItem that separates groups of other
+  #GtkToolItems. Depending on the theme, a #GtkSeparatorToolItem will
+  often look like a vertical line on horizontally docked toolbars.
+</para>
+<para>
+  Use gtk_separator_tool_item_new() to create a new #GtkSeparatorToolItem.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+  <variablelist>
+    <varlistentry>
+      <term>#GtkToolbar</term>
+      <listitem><para>The toolbar widget</para></listitem>
+    </varlistentry>
+    <varlistentry>
+      <term>#GtkRadioToolButton</term>
+      <listitem><para>A toolbar item containing a radio
+	  button</para></listitem>
+    </varlistentry>
+  </variablelist>
 </para>
 
 <!-- ##### STRUCT GtkSeparatorToolItem ##### -->
 <para>
-
+The #GtkSeparatorToolItem struct contains only private data and
+should only be accessed through the functions described below.
 </para>
 
 
diff --git a/docs/reference/gtk/tmpl/gtktogglebutton.sgml b/docs/reference/gtk/tmpl/gtktogglebutton.sgml
index 4771692f93..23ac0d32e3 100644
--- a/docs/reference/gtk/tmpl/gtktogglebutton.sgml
+++ b/docs/reference/gtk/tmpl/gtktogglebutton.sgml
@@ -58,18 +58,22 @@ void make_toggles (void) {
 <!-- ##### SECTION See_Also ##### -->
 <para>
 <variablelist>
+
 <varlistentry>
-<term>#GtkButton</term>
-<listitem><para>a more general button.</para></listitem>
+  <term>#GtkButton</term>
+  <listitem><para>a more general button.</para></listitem>
 </varlistentry>
+
 <varlistentry>
-<term>#GtkCheckButton</term>
-<listitem><para>another way of presenting a toggle option.</para></listitem>
+  <term>#GtkCheckButton</term>
+  <listitem><para>another way of presenting a toggle option.</para></listitem>
 </varlistentry>
+
 <varlistentry>
-<term>#GtkCheckMenuItem</term>
-<listitem><para>a #GtkToggleButton  as a menu item.</para></listitem>
+  <term>#GtkCheckMenuItem</term>
+  <listitem><para>a #GtkToggleButton  as a menu item.</para></listitem>
 </varlistentry>
+
 </variablelist>
 </para>
 
diff --git a/docs/reference/gtk/tmpl/gtktoggletoolbutton.sgml b/docs/reference/gtk/tmpl/gtktoggletoolbutton.sgml
index 13154e4054..ba2312c82d 100644
--- a/docs/reference/gtk/tmpl/gtktoggletoolbutton.sgml
+++ b/docs/reference/gtk/tmpl/gtktoggletoolbutton.sgml
@@ -2,21 +2,48 @@
 gtktoggletoolbutton
 
 <!-- ##### SECTION Short_Description ##### -->
-
+A #GtkToolItem containing a toggle button.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+  A #GtkToggleToolButton is a #GtkToolItem that contains a toggle
+  button.
+</para>
 
+<para>
+  Use gtk_toggle_tool_button_new() to create a new
+  #GtkToggleToolButton. Use gtk_toggle_tool_button_new_from_stock() to
+  create a new #GtkToggleToolButton containing a stock item.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
-<para>
 
+<para>
+  <varlistentry>
+    <term>#GtkToolbar</term>
+    <listitem><para>The toolbar widget</para></listitem>
+    <term>#GtkToolButton</term>
+    <listitem>
+      <para>
+	The parent class of #GtkToggleToolButton. The properties
+	"label_widget", "label", "icon_widget", and "stock_id" on
+	#GtkToolButton determine the label and icon used on
+	#GtkToggleToolButton<!-- -->s.
+      </para>
+    </listitem>
+    <term>#GtkSeparatorToolItem</term>
+    <listitem>
+      <para>A subclass of #GtkToolItem that separates groups of
+	items on a toolbar.
+      </para>
+    </listitem>
+  </varlistentry>
 </para>
 
 <!-- ##### STRUCT GtkToggleToolButton ##### -->
 <para>
-
+  The #GtkToggleToolButton struct contains only private data and
+  should only be accessed through the functions described below.
 </para>
 
 
diff --git a/docs/reference/gtk/tmpl/gtktoolbar.sgml b/docs/reference/gtk/tmpl/gtktoolbar.sgml
index 5b112ba445..51cbc29c12 100644
--- a/docs/reference/gtk/tmpl/gtktoolbar.sgml
+++ b/docs/reference/gtk/tmpl/gtktoolbar.sgml
@@ -2,42 +2,41 @@
 GtkToolbar
 
 <!-- ##### SECTION Short_Description ##### -->
-create bars of buttons and other widgets.
+Create bars of buttons and other widgets.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
 A toolbar is created with a call to gtk_toolbar_new().
 </para>
 <para>
-Buttons with text and/or images are added with gtk_toolbar_append_item(), gtk_toolbar_prepend_item(), and gtk_toolbar_insert_item().
+A toolbar can contain instances of a subclass of #GtkToolItem. To add
+a #GtkToolItem to the a toolbar, use gtk_toolbar_insert(). To remove
+an item from the toolbar use gtk_container_remove(). To add a button
+to the toolbar, add an instance of #GtkToolButton. Toolbar items can
+be visually grouped by adding instances of #GtkSeparatorToolItem to
+the toolbar.
 </para>
 <para>
-Any of #GtkToggleButton, #GtkRadioButton, or an arbitrary widget can be added to the toolbar with gtk_toolbar_append_element(), gtk_toolbar_prepend_element(), and gtk_toolbar_insert_element().
-</para>
-<para>
-Widgets can be visibly grouped by adding gaps between widgets using gtk_toolbar_append_space(), gtk_toolbar_prepend_space(), and gtk_toolbar_insert_space().
+Creating a context menu for the toolbar can be done by connecting to
+the #GtkToolbar::popup-context-menu signal.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
 <variablelist>
+
 <varlistentry>
-<term>#GtkToolTips</term>
-<listitem><para>Change the properties of a #GtkToolbar's #GtkTooltips.</para></listitem>
-</varlistentry>
-<varlistentry>
-<term>#GtkTipsQuery</term>
-<listitem><para>Make use of the private tips of toolbar elements.</para></listitem>
+<term>#GtkToolItem</term>
+<listitem><para>Base class of widgets that can be added to a toolbar.</para></listitem>
 </varlistentry>
+
 </variablelist>
 </para>
 
 <!-- ##### STRUCT GtkToolbar ##### -->
 <para>
-<structfield>num_children</structfield> is an integer specifying how many toolbar items the #GtkToolbar contains. <structfield>children</structfield> is a #GList of the child widgets of the toolbar.
-</para>
-<para>
-<structfield>orientation</structfield>
+The #GtkToolbar struct only contains private data and should only be
+accessed through the function described below.
 </para>
 
 
diff --git a/docs/reference/gtk/tmpl/gtktoolbutton.sgml b/docs/reference/gtk/tmpl/gtktoolbutton.sgml
index 6fa2e61e28..cc49be6435 100644
--- a/docs/reference/gtk/tmpl/gtktoolbutton.sgml
+++ b/docs/reference/gtk/tmpl/gtktoolbutton.sgml
@@ -2,21 +2,70 @@
 GtkToolButton
 
 <!-- ##### SECTION Short_Description ##### -->
-
+A #GtkToolItem subclass that displays buttons
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
+#GtkToolButton<!-- -->s are #GtkToolItems containing buttons.
+</para>
+
+<para>
+Use gtk_tool_button_new() to create a new #GtkToolButton. Use
+gtk_tool_button_new_with_stock() to create a #GtkToolButton
+containing a stock item.
+</para>
 
+<para>
+The label of a #GtkToolButton is determined by the properties
+"label_widget", "label", and "stock_id". If "label_widget" is
+non-%NULL, then that widget is used as the label. Otherwise, if
+"label" is non-%NULL, that string is used as the label. Otherwise, if
+"stock_id" is non-%NULL, the label is determined by the stock
+item. Otherwise, the button does not have a label.
+</para>
+
+<para>
+The icon of a #GtkToolButton is determined by the properties
+"icon_widget" and "stock_id". If "icon_widget" is non-%NULL, then
+that widget is used as the icon. Otherwise, if "stock_id" is
+non-%NULL, the icon is determined by the stock item. Otherwise,
+the button does not have a label.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
+<variablelist>
+
+<varlistentry>
+<term>#GtkToolbar</term>
+<listitem><para>The toolbar widget</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>#GtkToggleToolButton</term>
+<listitem><para>A subclass of #GtkToolButton that displays toggle
+    buttons on the toolbar</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term>#GtkRadioToolButton</term>
+<listitem><para>A subclass of #GtkToolButton that displays radio
+    buttons on the toolbar</para></listitem>
+</varlistentry>
 
+<varlistentry>
+<term>#GtkSeparatorToolItem</term>
+<listitem><para>A subclass of #GtkToolItem that separates groups of
+    items on a toolbar</para></listitem>
+</varlistentry>
+
+</variablelist>
 </para>
 
 <!-- ##### STRUCT GtkToolButton ##### -->
 <para>
-
+The #GtkToolButton struct contains only private. It should only be
+accessed with the function described below.
 </para>
 
 
@@ -99,7 +148,7 @@ GtkToolButton
 </para>
 
 @button: 
-@icon: 
+@icon_widget: 
 
 
 <!-- ##### FUNCTION gtk_tool_button_get_icon_widget ##### -->
diff --git a/docs/reference/gtk/tmpl/gtktoolitem.sgml b/docs/reference/gtk/tmpl/gtktoolitem.sgml
index 8cc55bb9d7..8493a05662 100644
--- a/docs/reference/gtk/tmpl/gtktoolitem.sgml
+++ b/docs/reference/gtk/tmpl/gtktoolitem.sgml
@@ -2,21 +2,50 @@
 GtkToolItem
 
 <!-- ##### SECTION Short_Description ##### -->
-
+#GtkToolItem is the base class of widgets that can be added to
+#GtkToolbar.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+#GtkToolItem<!-- -->s are widgets that can appear on a toolbar. To
+create a toolbar item that contain something else than a button, use
+gtk_tool_item_new(). Use gtk_container_add() to add a child
+widget to the tool item.
+</para>
+<para>
+For toolbar items that contain buttons, see the #GtkToolButton,
+#GtkToggleToolButton and #GtkRadioToolButton classes.
+</para>
+See the #GtkToolbar class for a description of the toolbar widget.
+<para>
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
 
+<varlistentry>
+  <term>#GtkToolbar</term>
+  <listitem><para>The toolbar widget</para></listitem>
+</varlistentry>
+
+<varlistentry>
+  <term>#GtkToolButton</term>
+  <listitem><para>A subclass of #GtkToolItem that displays buttons on
+      the toolbar</para></listitem>
+</varlistentry>
+
+<varlistentry>
+  <term>#GtkSeparatorToolItem</term>
+  <listitem><para>A subclass of #GtkToolItem that separates groups of
+      items on a toolbar</para></listitem>
+</varlistentry>
+
 </para>
 
 <!-- ##### STRUCT GtkToolItem ##### -->
 <para>
-
+The GtkToolItem struct contains only private data. It should only be
+accessed through the functions described below.
 </para>
 
 
@@ -135,7 +164,7 @@ GtkToolItem
 </para>
 
 @toolitem: 
-@visible_horizontal: 
+@visible_vertical: 
 
 
 <!-- ##### FUNCTION gtk_tool_item_get_visible_vertical ##### -->
@@ -229,6 +258,11 @@ GtkToolItem
 
 @toolitem: the object which received the signal.
 
+<!-- ##### ARG GtkToolItem:is-important ##### -->
+<para>
+
+</para>
+
 <!-- ##### ARG GtkToolItem:visible-horizontal ##### -->
 <para>
 
diff --git a/gtk/gtkradiotoolbutton.c b/gtk/gtkradiotoolbutton.c
index 8f7471a598..8f9d4e94e8 100644
--- a/gtk/gtkradiotoolbutton.c
+++ b/gtk/gtkradiotoolbutton.c
@@ -71,6 +71,16 @@ gtk_radio_tool_button_init (GtkRadioToolButton *button)
   gtk_toggle_button_set_mode (GTK_TOGGLE_BUTTON (_gtk_tool_button_get_button (tool_button)), FALSE);
 }
 
+/**
+ * gtk_radio_tool_button_new:
+ * @group: An existing radio button group, or %NULL if you are creating a new group
+ * 
+ * Creates a new #GtkRadioToolButton, adding it to @group.
+ * 
+ * Return value: The new #GtkRadioToolButton
+ * 
+ * Since: 2.4
+ **/
 GtkToolItem *
 gtk_radio_tool_button_new (GSList *group)
 {
@@ -84,6 +94,19 @@ gtk_radio_tool_button_new (GSList *group)
   return GTK_TOOL_ITEM (button);
 }
 
+/**
+ * gtk_radio_tool_button_new_from_stock:
+ * @group: an existing radio button group, or %NULL if you are creating a new group
+ * @stock_id: the name of a stock item
+ * 
+ * Creates a new #GtkRadioToolButton, adding it to @group. 
+ * The new #GtkRadioToolButton will contain an icon and label from the
+ * stock item indicated by @stock_id.
+ * 
+ * Return value: The new #GtkRadioToolItem
+ * 
+ * Since: 2.4
+ **/
 GtkToolItem *
 gtk_radio_tool_button_new_from_stock (GSList      *group,
 				      const gchar *stock_id)
@@ -102,9 +125,18 @@ gtk_radio_tool_button_new_from_stock (GSList      *group,
   return GTK_TOOL_ITEM (button);
 }
 
+/**
+ * gtk_radio_tool_button_new_from_widget:
+ * @group: An existing #GtkRadioToolButton
+ * 
+ * Creates a new #GtkRadioToolButton adding it to the same group as @gruup
+ * 
+ * Return value: The new #GtkRadioToolButton
+ * 
+ * Since: 2.4
+ **/
 GtkToolItem *
-gtk_radio_tool_button_new_from_widget (GtkWidget   *group,
-				       const gchar *stock_id)
+gtk_radio_tool_button_new_from_widget (GtkWidget   *group)
 {
   GSList *list = NULL;
   
@@ -113,11 +145,25 @@ gtk_radio_tool_button_new_from_widget (GtkWidget   *group,
   if (group)
     list = gtk_radio_tool_button_get_group (GTK_RADIO_TOOL_BUTTON (group));
   
-  return gtk_radio_tool_button_new_from_stock (list, stock_id);
+  return gtk_radio_tool_button_new (list);
 }
 
+/**
+ * gtk_radio_tool_button_new_with_stock_from_widget:
+ * @group: An existing #GtkRadioToolButton.
+ * @stock_id: the name of a stock item 
+ * 
+ * Creates a new #GtkRadioToolButton adding it to the same group as @group.
+ * The new #GtkRadioToolButton will contain an icon and label from the
+ * stock item indicated by @stock_id.
+ * 
+ * Return value: A new #GtkRadioToolButton
+ * 
+ * Since: 2.4
+ **/
 GtkToolItem *
-gtk_radio_tool_button_new_with_stock_from_widget (GtkWidget *group)
+gtk_radio_tool_button_new_with_stock_from_widget (GtkWidget   *group,
+						  const gchar *stock_id)
 {
   GSList *list = NULL;
   
@@ -126,7 +172,7 @@ gtk_radio_tool_button_new_with_stock_from_widget (GtkWidget *group)
   if (group)
     list = gtk_radio_tool_button_get_group (GTK_RADIO_TOOL_BUTTON (group));
   
-  return gtk_radio_tool_button_new (list);
+  return gtk_radio_tool_button_new_from_stock (list, stock_id);
 }
 
 static GtkRadioButton *
@@ -135,6 +181,16 @@ get_radio_button (GtkRadioToolButton *button)
   return GTK_RADIO_BUTTON (_gtk_tool_button_get_button (GTK_TOOL_BUTTON (button)));
 }
 
+/**
+ * gtk_radio_tool_button_get_group:
+ * @button: a #GtkRadioToolButton
+ *
+ * Returns the radio button group @button belongs to.
+ * 
+ * Return value: The group @button belongs to.
+ * 
+ * Since: 2.4
+ **/
 GSList *
 gtk_radio_tool_button_get_group (GtkRadioToolButton *button)
 {
@@ -143,6 +199,15 @@ gtk_radio_tool_button_get_group (GtkRadioToolButton *button)
   return gtk_radio_button_get_group (get_radio_button (button));
 }
 
+/**
+ * gtk_radio_tool_button_set_group:
+ * @button: a #GtkRadioToolButton
+ * @group: an existing radio button group
+ * 
+ * Adds @button to @group, removing it from the group it belonged to before.
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_radio_tool_button_set_group (GtkRadioToolButton *button,
 				 GSList             *group)
diff --git a/gtk/gtkradiotoolbutton.h b/gtk/gtkradiotoolbutton.h
index e6068ea526..1d0ffdc23c 100644
--- a/gtk/gtkradiotoolbutton.h
+++ b/gtk/gtkradiotoolbutton.h
@@ -56,9 +56,9 @@ GType        gtk_radio_tool_button_get_type       (void) G_GNUC_CONST;
 GtkToolItem *gtk_radio_tool_button_new                        (GSList             *group);
 GtkToolItem *gtk_radio_tool_button_new_from_stock             (GSList             *group,
 							       const gchar        *stock_id);
-GtkToolItem *gtk_radio_tool_button_new_from_widget            (GtkWidget          *group,
+GtkToolItem *gtk_radio_tool_button_new_from_widget            (GtkWidget          *group);
+GtkToolItem *gtk_radio_tool_button_new_with_stock_from_widget (GtkWidget          *group,
 							       const gchar        *stock_id);
-GtkToolItem *gtk_radio_tool_button_new_with_stock_from_widget (GtkWidget          *group);
 GSList *     gtk_radio_tool_button_get_group                  (GtkRadioToolButton *button);
 void         gtk_radio_tool_button_set_group                  (GtkRadioToolButton *button,
 							       GSList             *group);
diff --git a/gtk/gtkseparatortoolitem.c b/gtk/gtkseparatortoolitem.c
index 0f1e3ad9ec..34015b888b 100644
--- a/gtk/gtkseparatortoolitem.c
+++ b/gtk/gtkseparatortoolitem.c
@@ -34,8 +34,12 @@
 #define SPACE_LINE_START    3
 #define SPACE_LINE_END      7
 
+#define MENU_ID "gtk-separator-tool-item-menu-id"
+
 static void                 gtk_separator_tool_item_class_init (GtkSeparatorToolItemClass *class);
+static gboolean             gtk_separator_tool_item_create_menu_proxy (GtkToolItem *item);
 static void		    gtk_separator_tool_item_size_request (GtkWidget      *widget,
+								  
 								  GtkRequisition *requisition);
 static gboolean             gtk_separator_tool_item_expose     (GtkWidget                 *widget,
 								GdkEventExpose            *event);
@@ -119,7 +123,8 @@ gtk_separator_tool_item_class_init (GtkSeparatorToolItemClass *class)
 
   widget_class->size_request = gtk_separator_tool_item_size_request;
   widget_class->expose_event = gtk_separator_tool_item_expose;
-  
+  toolitem_class->create_menu_proxy = gtk_separator_tool_item_create_menu_proxy;
+
   container_class->add = gtk_separator_tool_item_add;
 }
 
@@ -130,6 +135,18 @@ gtk_separator_tool_item_add (GtkContainer *container,
   g_warning("attempt to add a child to an GtkSeparatorToolItem");
 }
 
+static gboolean
+gtk_separator_tool_item_create_menu_proxy (GtkToolItem *item)
+{
+  GtkWidget *menu_item = NULL;
+  
+  menu_item = gtk_separator_menu_item_new();
+  
+  gtk_tool_item_set_proxy_menu_item (item, MENU_ID, menu_item);
+  
+  return TRUE;
+}
+
 static void
 gtk_separator_tool_item_size_request (GtkWidget      *widget,
 				      GtkRequisition *requisition)
@@ -193,6 +210,15 @@ gtk_separator_tool_item_expose (GtkWidget      *widget,
   return TRUE;
 }
 
+/**
+ * gtk_separator_tool_item_new:
+ * 
+ * Create a new #GtkSeparatorToolItem
+ * 
+ * Return value: the new #GtkSeparatorToolItem
+ * 
+ * Since: 2.4
+ **/
 GtkToolItem *
 gtk_separator_tool_item_new (void)
 {
diff --git a/gtk/gtktoggletoolbutton.c b/gtk/gtktoggletoolbutton.c
index 1cdb0238b0..81f7d61032 100644
--- a/gtk/gtktoggletoolbutton.c
+++ b/gtk/gtktoggletoolbutton.c
@@ -94,6 +94,12 @@ gtk_toggle_tool_button_class_init (GtkToggleToolButtonClass *klass)
   toolitem_class->create_menu_proxy = gtk_toggle_tool_button_create_menu_proxy;
   toolbutton_class->button_type = GTK_TYPE_TOGGLE_BUTTON;
   
+/**
+ * GtkToggleToolButton::toggled:
+ * @toggle_tool_button: the object that emitted the signal
+ *
+ * Emitted whenever the toggle tool button changes state.
+ **/
   toggle_signals[TOGGLED] =
     g_signal_new ("toggled",
 		  G_OBJECT_CLASS_TYPE (klass),
@@ -214,6 +220,15 @@ button_toggled (GtkWidget           *widget,
     }
 }
 
+/**
+ * gtk_toggle_tool_button_new:
+ * 
+ * Returns a new #GtkToggleToolButton
+ * 
+ * Return value: a newly created #GtkToggleToolButton
+ * 
+ * Since: 2.4
+ **/
 GtkToolItem *
 gtk_toggle_tool_button_new (void)
 {
@@ -225,6 +240,20 @@ gtk_toggle_tool_button_new (void)
   return GTK_TOOL_ITEM (button);
 }
 
+/**
+ * gtk_toggle_tool_button_new_from_stock:
+ * @stock_id: the name of the stock item 
+ *
+ * Creates a new #GtkToggleToolButton containing the image and text from a
+ * stock item. Some stock ids have preprocessor macros like #GTK_STOCK_OK
+ * and #GTK_STOCK_APPLY.
+ *
+ * It is an error if @stock_id is not a name of a stock item.
+ * 
+ * Return value: A new #GtkToggleToolButton
+ * 
+ * Since: 2.4
+ **/
 GtkToolItem *
 gtk_toggle_tool_button_new_from_stock (const gchar *stock_id)
 {
@@ -239,6 +268,17 @@ gtk_toggle_tool_button_new_from_stock (const gchar *stock_id)
   return GTK_TOOL_ITEM (button);
 }
 
+/**
+ * gtk_toggle_tool_button_set_active:
+ * @button: a #GtkToggleToolButton
+ * @is_active: whether @button should be active
+ * 
+ * Sets the status of the toggle tool button. Set to %TRUE if you
+ * want the GtkToggleButton to be 'pressed in', and %FALSE to raise it.
+ * This action causes the toggled signal to be emitted.
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_toggle_tool_button_set_active (GtkToggleToolButton *button,
 				   gboolean is_active)
@@ -251,6 +291,17 @@ gtk_toggle_tool_button_set_active (GtkToggleToolButton *button,
     gtk_button_clicked (GTK_BUTTON (_gtk_tool_button_get_button (GTK_TOOL_BUTTON (button))));
 }
 
+/**
+ * gtk_toggle_tool_button_get_active:
+ * @button: a #GtkToggleToolButton
+ * 
+ * Queries a #GtkToggleToolButton and returns its current state.
+ * Returns %TRUE if the toggle button is pressed in and %FALSE if it is raised.
+ * 
+ * Return value: %TRUE if the toggle tool button is pressed in, %FALSE if not
+ * 
+ * Since: 2.4
+ **/
 gboolean
 gtk_toggle_tool_button_get_active (GtkToggleToolButton *button)
 {
diff --git a/gtk/gtktoolbar.c b/gtk/gtktoolbar.c
index 2ad65e552b..adaac5ed8d 100644
--- a/gtk/gtktoolbar.c
+++ b/gtk/gtktoolbar.c
@@ -310,8 +310,15 @@ gtk_toolbar_class_init (GtkToolbarClass *klass)
   klass->orientation_changed = gtk_toolbar_real_orientation_changed;
   klass->style_changed = gtk_toolbar_real_style_changed;
   
+/**
+ * GtkToolbar::orientation-changed:
+ * @toolbar: the object which emitted the signal
+ * @orientation: the new #GtkOrientation of the toolbar
+ *
+ * Emitted when the orientation of the toolbar changes.
+ */
   toolbar_signals[ORIENTATION_CHANGED] =
-    g_signal_new ("orientation_changed",
+    g_signal_new ("orientation-changed",
 		  G_OBJECT_CLASS_TYPE (klass),
 		  G_SIGNAL_RUN_FIRST,
 		  G_STRUCT_OFFSET (GtkToolbarClass, orientation_changed),
@@ -319,8 +326,15 @@ gtk_toolbar_class_init (GtkToolbarClass *klass)
 		  g_cclosure_marshal_VOID__ENUM,
 		  G_TYPE_NONE, 1,
 		  GTK_TYPE_ORIENTATION);
+/**
+ * GtkToolbar::style-changed:
+ * @toolbar: The #GtkToolbar which emitted the signal
+ * @style: the new #GtkToolbarStyle of the toolbar
+ *
+ * Emitted when the style of the toolbar changes. 
+ */
   toolbar_signals[STYLE_CHANGED] =
-    g_signal_new ("style_changed",
+    g_signal_new ("style-changed",
 		  G_OBJECT_CLASS_TYPE (klass),
 		  G_SIGNAL_RUN_FIRST,
 		  G_STRUCT_OFFSET (GtkToolbarClass, style_changed),
@@ -328,6 +342,24 @@ gtk_toolbar_class_init (GtkToolbarClass *klass)
 		  g_cclosure_marshal_VOID__ENUM,
 		  G_TYPE_NONE, 1,
 		  GTK_TYPE_TOOLBAR_STYLE);
+/**
+ * GtkToolbar::popup-context-menu:
+ * @toolbar: the #GtkToolbar which emitted the signal
+ * @x: the x coordinate of the point where the menu should appear
+ * @y: the y coordinate of the point where the menu should appear
+ * @button: the mouse button the user pressed, or -1
+ *
+ * Emitted when the user right-clicks the toolbar or uses the
+ * keybinding to display a popup menu.
+ *
+ * Application developers should handle this signal if they want
+ * to display a context menu on the toolbar. The context-menu should
+ * appear at the coordinates given by @x and @y. The mouse button
+ * number is given by the @button parameter. If the menu was popped
+ * up using the keybaord, @button is -1.
+ *
+ * Return value: return %TRUE if the signal was handled, %FALSE if not
+ */
   toolbar_signals[POPUP_CONTEXT_MENU] =
     g_signal_new ("popup_context_menu",
 		  G_OBJECT_CLASS_TYPE (klass),
@@ -338,6 +370,16 @@ gtk_toolbar_class_init (GtkToolbarClass *klass)
 		  G_TYPE_BOOLEAN, 3,
 		  G_TYPE_INT, G_TYPE_INT,
 		  G_TYPE_INT);
+/**
+ * GtkToolbar::move-focus:
+ * @toolbar: the #GtkToolbar which emitted the signal
+ * @dir: a #GtkDirection
+ *
+ * A keybinding signal used internally by GTK+. This signal can't
+ * be used in application code.
+ *
+ * Return value: %TRUE if the signal was handled, %FALSE if not
+ */
   toolbar_signals[MOVE_FOCUS] =
     _gtk_binding_signal_new ("move_focus",
 			     G_TYPE_FROM_CLASS (klass),
@@ -347,6 +389,16 @@ gtk_toolbar_class_init (GtkToolbarClass *klass)
 			     _gtk_marshal_BOOLEAN__ENUM,
 			     G_TYPE_BOOLEAN, 1,
 			     GTK_TYPE_DIRECTION_TYPE);
+/**
+ * GtkToolbar::focus-home-or-end:
+ * @toolbar: the #GtkToolbar which emitted the signal
+ * @focus_home: %TRUE if the first item should be focused
+ *
+ * A keybinding signal used internally by GTK+. This signal can't
+ * be used in application code
+ *
+ * Return value: %TRUE if the signal was handled, %FALSE if not
+ */
   toolbar_signals[FOCUS_HOME_OR_END] =
     _gtk_binding_signal_new ("focus_home_or_end",
 			     G_OBJECT_CLASS_TYPE (klass),
@@ -565,9 +617,22 @@ toolbar_item_visible (GtkToolbar  *toolbar,
 }
 
 static gboolean
-toolbar_item_is_homogeneous (GtkToolItem *item)
+toolbar_item_is_homogeneous (GtkToolbar  *toolbar,
+			     GtkToolItem *item)
 {
-  return (gtk_tool_item_get_homogeneous (item) && !GTK_IS_SEPARATOR_TOOL_ITEM (item));
+  gboolean result = FALSE;
+
+  if ((gtk_tool_item_get_homogeneous (item) && !GTK_IS_SEPARATOR_TOOL_ITEM (item)))
+    result = TRUE;
+
+  if (gtk_tool_item_get_is_important (item) &&
+      toolbar->style == GTK_TOOLBAR_BOTH_HORIZ &&
+      toolbar->orientation == GTK_ORIENTATION_HORIZONTAL)
+    {
+      result = FALSE;
+    }
+
+  return result;
 }
 
 static void
@@ -799,7 +864,7 @@ gtk_toolbar_size_request (GtkWidget      *widget,
       max_child_width = MAX (max_child_width, requisition.width);
       max_child_height = MAX (max_child_height, requisition.height);
 
-      if (toolbar_item_is_homogeneous (item))
+      if (toolbar_item_is_homogeneous (toolbar, item))
 	{
 	  max_homogeneous_child_width = MAX (max_homogeneous_child_width, requisition.width);
 	  max_homogeneous_child_height = MAX (max_homogeneous_child_height, requisition.height);
@@ -821,7 +886,7 @@ gtk_toolbar_size_request (GtkWidget      *widget,
       if (!toolbar_item_visible (toolbar, item))
 	continue;
       
-      if (toolbar_item_is_homogeneous (item))
+      if (toolbar_item_is_homogeneous (toolbar, item))
 	{
 	  size = homogeneous_size;
 	}
@@ -924,14 +989,14 @@ get_item_size (GtkToolbar *toolbar,
   
   if (toolbar->orientation == GTK_ORIENTATION_HORIZONTAL)
     {
-      if (toolbar_item_is_homogeneous (item))
+      if (toolbar_item_is_homogeneous (toolbar, item))
 	return toolbar->button_maxw;
       else
 	return requisition.width;
     }
   else
     {
-      if (toolbar_item_is_homogeneous (item))
+      if (toolbar_item_is_homogeneous (toolbar, item))
 	return toolbar->button_maxh;
       else
 	return requisition.height;
@@ -2162,6 +2227,18 @@ gtk_toolbar_new (void)
   return GTK_WIDGET (toolbar);
 }
 
+/**
+ * gtk_toolbar_insert:
+ * @toolbar: a #GtkToolbar
+ * @item: a #GtkToolItem
+ * @pos: the position of the new item
+ *
+ * Insert a #GtkToolItem into the toolbar at position @pos. If @pos is
+ * 0 the item is prepended to the start of the toolbar. If @pos is
+ * negative, append the item to the end of the toolbar.
+ *
+ * Since: 2.4
+ **/
 void
 gtk_toolbar_insert (GtkToolbar  *toolbar,
 		    GtkToolItem *item,
@@ -2176,6 +2253,18 @@ gtk_toolbar_insert (GtkToolbar  *toolbar,
   gtk_toolbar_insert_tool_item (toolbar, item, pos);
 }
 
+/**
+ * gtk_toolbar_get_item_index:
+ * @toolbar: a #GtkToolbar
+ * @item: a #GtkToolItem that is a child of @toolbar
+ * 
+ * Returns the position of @item on the toolbar, starting from 0.
+ * It is an error if @item is not a child of the toolbar.
+ * 
+ * Return value: the position of item on the toolbar.
+ * 
+ * Since: 2.4
+ **/
 gint
 gtk_toolbar_get_item_index (GtkToolbar  *toolbar,
 			    GtkToolItem *item)
@@ -2331,6 +2420,16 @@ gtk_toolbar_get_tooltips (GtkToolbar *toolbar)
   return toolbar->tooltips->enabled;
 }
 
+/**
+ * gtk_toolbar_get_n_items:
+ * @toolbar: a #GtkToolbar
+ * 
+ * Returns the number of items on the toolbar.
+ * 
+ * Return value: the number of items on the toolbar
+ * 
+ * Since: 2.4
+ **/
 gint
 gtk_toolbar_get_n_items (GtkToolbar *toolbar)
 {
@@ -2346,9 +2445,19 @@ gtk_toolbar_get_n_items (GtkToolbar *toolbar)
   return g_list_length (priv->items);
 }
 
-/*
- * returns NULL if n is out of range
- */
+/**
+ * gtk_toolbar_get_nth_item:
+ * @toolbar: a #GtkToolbar
+ * @n: A position on the toolbar
+ *
+ * Returns the @n<!-- -->'s item on @toolbar, or %NULL if the
+ * toolbar does not contain an @n<!-- -->'th item.
+ * 
+ * Return value: The @n<!-- -->'th #GtkToolItem on @toolbar, or %NULL if there
+ * isn't an @n<!-- -->th item.
+ * 
+ * Since: 2.4
+ **/
 GtkToolItem *
 gtk_toolbar_get_nth_item (GtkToolbar *toolbar,
 			  gint        n)
@@ -2409,6 +2518,17 @@ gtk_toolbar_get_icon_size (GtkToolbar *toolbar)
   return toolbar->icon_size;
 }
 
+/**
+ * gtk_toolbar_get_relief_style:
+ * @toolbar: a #GtkToolbar
+ * 
+ * Returns the relief style of buttons on @toolbar. See
+ * gtk_button_set_relief_style().
+ * 
+ * Return value: The relief style of buttons on @toolbar.
+ * 
+ * Since: 2.4
+ **/
 GtkReliefStyle
 gtk_toolbar_get_relief_style (GtkToolbar *toolbar)
 {
@@ -2451,6 +2571,18 @@ gtk_toolbar_unset_icon_size (GtkToolbar *toolbar)
     }
 }
 
+/**
+ * gtk_toolbar_set_show_arrow:
+ * @toolbar: a #GtkToolbar
+ * @show_arrow: Whether to show an overflow menu
+ * 
+ * Sets whether to show an overflow menu when
+ * @toolbar doesn't have room for all items on it. If %TRUE,
+ * items that there are not room are available through an
+ * overflow menu.
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_toolbar_set_show_arrow (GtkToolbar *toolbar,
 			    gboolean    show_arrow)
@@ -2474,6 +2606,17 @@ gtk_toolbar_set_show_arrow (GtkToolbar *toolbar,
     }
 }
 
+/**
+ * gtk_toolbar_get_show_arrow:
+ * @toolbar: a #GtkToolbar
+ * 
+ * Returns whether the toolbar has an overflow menu.
+ * See gtk_toolbar_set_show_arrow()
+ * 
+ * Return value: 
+ * 
+ * Since: 2.4
+ **/
 gboolean
 gtk_toolbar_get_show_arrow (GtkToolbar *toolbar)
 {
@@ -2489,6 +2632,23 @@ gtk_toolbar_get_show_arrow (GtkToolbar *toolbar)
   return priv->show_arrow;
 }
 
+/**
+ * gtk_toolbar_get_drop_index:
+ * @toolbar: a #GtkToolbar
+ * @x: x coordinate of a point on the toolbar
+ * @y: y coordinate of a point on the toolbar
+ *
+ * Returns the position corresponding to the indicated point on
+ * @toolbar. This is useful when dragging items to the toolbar:
+ * this function returns the position a new item should be
+ * inserted.
+ *
+ * @x and @y are in @toolbar coordinates.
+ * 
+ * Return value: The position corresponding to the point (@x, @y) on the toolbar.
+ * 
+ * Since: 2.4
+ **/
 gint
 gtk_toolbar_get_drop_index (GtkToolbar *toolbar,
 			    gint        x,
diff --git a/gtk/gtktoolbutton.c b/gtk/gtktoolbutton.c
index 93c241ce5f..349fbda30b 100644
--- a/gtk/gtktoolbutton.c
+++ b/gtk/gtktoolbutton.c
@@ -62,6 +62,8 @@ static void gtk_tool_button_get_property  (GObject            *object,
 					   guint               prop_id,
 					   GValue             *value,
 					   GParamSpec         *pspec);
+static void gtk_tool_button_property_notify (GObject          *object,
+					     GParamSpec       *pspec);
 static void gtk_tool_button_finalize      (GObject            *object);
 
 static void gtk_tool_button_toolbar_reconfigured (GtkToolItem *tool_item);
@@ -128,6 +130,7 @@ gtk_tool_button_class_init (GtkToolButtonClass *klass)
   
   object_class->set_property = gtk_tool_button_set_property;
   object_class->get_property = gtk_tool_button_get_property;
+  object_class->notify = gtk_tool_button_property_notify;
   object_class->finalize = gtk_tool_button_finalize;
 
   tool_item_class->create_menu_proxy = gtk_tool_button_create_menu_proxy;
@@ -160,10 +163,12 @@ gtk_tool_button_class_init (GtkToolButtonClass *klass)
    *                      underscore is followed by another underscore
    *
    *			- an underscore indicates that the next character when
-   *                      used in the overflow menu should be used as a mnemonic.
+   *                      used in the overflow menu should be used as a
+   *                      mnemonic.
    *
    *		In short: use_underline = TRUE means that the label text has
-   *            the form "_Open" and the toolbar should take appropriate action.
+   *            the form "_Open" and the toolbar should take appropriate
+   *            action.
    */
 
   g_object_class_install_property (object_class,
@@ -202,6 +207,13 @@ gtk_tool_button_class_init (GtkToolButtonClass *klass)
 							GTK_TYPE_WIDGET,
 							G_PARAM_READWRITE));
 
+/**
+ * GtkToolButton::clicked:
+ * @toolbutton: the object that emitted the signal
+ *
+ * This signal is emitted when the tool button is clicked with the mouse
+ * or activated with the keyboard.
+ **/
   toolbutton_signals[CLICKED] =
     g_signal_new ("clicked",
 		  G_OBJECT_CLASS_TYPE (klass),
@@ -278,8 +290,20 @@ gtk_tool_button_construct_contents (GtkToolItem *tool_item)
   
   if (style != GTK_TOOLBAR_TEXT)
     need_icon = TRUE;
+
+  if (style != GTK_TOOLBAR_ICONS && style != GTK_TOOLBAR_BOTH_HORIZ)
+    need_label = TRUE;
+
+  if (style == GTK_TOOLBAR_BOTH_HORIZ &&
+      (gtk_tool_item_get_is_important (GTK_TOOL_ITEM (button)) ||
+       gtk_tool_item_get_orientation (GTK_TOOL_ITEM (button)) == GTK_ORIENTATION_VERTICAL))
+    {
+      need_label = TRUE;
+    }
   
-  if (style != GTK_TOOLBAR_ICONS)
+  if (style != GTK_TOOLBAR_ICONS &&
+      ((style != GTK_TOOLBAR_BOTH_HORIZ ||
+	gtk_tool_item_get_is_important (GTK_TOOL_ITEM (button)))))
     need_label = TRUE;
   
   if (need_label)
@@ -361,8 +385,9 @@ gtk_tool_button_construct_contents (GtkToolItem *tool_item)
 
     case GTK_TOOLBAR_BOTH_HORIZ:
       box = gtk_hbox_new (FALSE, 0);
-      gtk_box_pack_start (GTK_BOX (box), icon, FALSE, TRUE, 0);
-      gtk_box_pack_start (GTK_BOX (box), label, TRUE, TRUE, 0);
+      gtk_box_pack_start (GTK_BOX (box), icon, label? FALSE : TRUE, TRUE, 0);
+      if (label)
+	gtk_box_pack_start (GTK_BOX (box), label, TRUE, TRUE, 0);
       gtk_container_add (GTK_CONTAINER (button->priv->button), box);
       break;
 
@@ -411,6 +436,14 @@ gtk_tool_button_set_property (GObject         *object,
 }
 
 static void
+gtk_tool_button_property_notify (GObject          *object,
+				 GParamSpec       *pspec)
+{
+  if (strcmp (pspec->name, "is_important"))
+    gtk_tool_button_construct_contents (GTK_TOOL_ITEM (object));
+}
+
+static void
 gtk_tool_button_get_property (GObject         *object,
 			      guint            prop_id,
 			      GValue          *value,
@@ -571,6 +604,20 @@ gtk_tool_button_toolbar_reconfigured (GtkToolItem *tool_item)
   gtk_tool_button_construct_contents (tool_item);
 }
 
+/**
+ * gtk_tool_button_new_from_stock:
+ * @stock_id: the name of the stock item 
+ *
+ * Creates a new #GtkToolButton containing the image and text from a
+ * stock item. Some stock ids have preprocessor macros like #GTK_STOCK_OK
+ * and #GTK_STOCK_APPLY.
+ *
+ * It is an error if @stock_id is not a name of a stock item.
+ * 
+ * Return value: A new #GtkToolButton
+ * 
+ * Since: 2.4
+ **/
 GtkToolItem *
 gtk_tool_button_new_from_stock (const gchar *stock_id)
 {
@@ -585,6 +632,18 @@ gtk_tool_button_new_from_stock (const gchar *stock_id)
   return GTK_TOOL_ITEM (button);
 }
 
+/**
+ * gtk_tool_button_new:
+ * @label: a string that will be used as label, or %NULL
+ * @icon_widget: a widget that will be used as icon widget, or %NULL
+ * 
+ * Creates a new %GtkToolButton using @icon_widget as icon and @label as
+ * label.
+ * 
+ * Return value: A new #GtkToolButton
+ * 
+ * Since: 2.4
+ **/
 GtkToolItem *
 gtk_tool_button_new (GtkWidget	 *icon_widget,
 		     const gchar *label)
@@ -603,6 +662,19 @@ gtk_tool_button_new (GtkWidget	 *icon_widget,
   return GTK_TOOL_ITEM (button);  
 }
 
+/**
+ * gtk_tool_button_set_label:
+ * @button: a #GtkToolButton
+ * @label: a string that will be used as label, or %NULL.
+ * 
+ * Sets @label as the label used for the tool button. The "label" property
+ * only has an effect if not overridden by a non-%NULL "label_widget" property.
+ * If both the "label_widget" and "label" properties are %NULL, the label
+ * is determined by the "stock_id" property. If the "stock_id" property is also
+ * %NULL, @button will not have a label.
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_tool_button_set_label (GtkToolButton *button,
 			   const gchar   *label)
@@ -622,6 +694,18 @@ gtk_tool_button_set_label (GtkToolButton *button,
     g_free (old_label);
 }
 
+/**
+ * gtk_tool_button_get_label:
+ * @button: a #GtkToolButton
+ * 
+ * Returns the label used by the tool button, or %NULL if the tool button
+ * doesn't have a label. or uses a the label from a stock item. The returned
+ * string is owned by GTK+, and must not be modified or freed.
+ * 
+ * Return value: The label, or %NULL
+ * 
+ * Since: 2.4
+ **/
 G_CONST_RETURN gchar *
 gtk_tool_button_get_label (GtkToolButton *button)
 {
@@ -630,6 +714,22 @@ gtk_tool_button_get_label (GtkToolButton *button)
   return button->priv->label_text;
 }
 
+/**
+ * gtk_tool_button_set_use_underline:
+ * @button: a #GtkToolButton
+ * @use_underline: whether the button label has the form "_Open"
+ *
+ * If set, an underline in the label property indicates that the next character
+ * should be used for the mnemonic accelerator key in the overflow menu. For
+ * example, if the label property is "_Open" and @use_underline is %TRUE,
+ * the label on the tool button will be "Open" and the item on the overflow
+ * menu will have an underlined 'O'.
+ * 
+ * Labels shown on tool buttons never have mnemonics on them; this property
+ * only affects the menu item on the overflow menu.
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_tool_button_set_use_underline (GtkToolButton *button,
 				   gboolean       use_underline)
@@ -648,6 +748,18 @@ gtk_tool_button_set_use_underline (GtkToolButton *button,
     }
 }
 
+/**
+ * gtk_tool_button_get_use_underline:
+ * @button: a #GtkToolButton
+ * 
+ * Returns whether underscores in the label property are used as mnemonics
+ * on menu items on the overflow menu. See gtk_tool_button_set_use_underline().
+ * 
+ * Return value: %TRUE if underscores in the label property are used as
+ * mnemonics on menu items on the overflow menu.
+ * 
+ * Since: 2.4
+ **/
 gboolean
 gtk_tool_button_get_use_underline (GtkToolButton *button)
 {
@@ -656,6 +768,17 @@ gtk_tool_button_get_use_underline (GtkToolButton *button)
   return button->priv->use_underline;
 }
 
+/**
+ * gtk_tool_button_set_stock_id:
+ * @button: a #GtkToolButton
+ * @stock_id: a name of a stock item, or %NULL
+ * 
+ * Sets the name of the stock item. See gtk_tool_button_new_from_stock().
+ * The stock_id property only has an effect if not
+ * overridden by non-%NULL "label" and "icon_widget" properties.
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_tool_button_set_stock_id (GtkToolButton *button,
 			      const gchar   *stock_id)
@@ -674,6 +797,17 @@ gtk_tool_button_set_stock_id (GtkToolButton *button,
   g_free (old_stock_id);
 }
 
+/**
+ * gtk_tool_button_get_stock_id:
+ * @button: a #GtkToolButton
+ * 
+ * Returns the name of the stock item. See gtk_tool_button_set_stock_id().
+ * The returned string is owned by GTK+ and must not be freed or modifed.
+ * 
+ * Return value: the name of the stock item for @button.
+ * 
+ * Since: 2.4
+ **/
 G_CONST_RETURN gchar *
 gtk_tool_button_get_stock_id (GtkToolButton *button)
 {
@@ -682,25 +816,36 @@ gtk_tool_button_get_stock_id (GtkToolButton *button)
   return button->priv->stock_id;
 }
 
+/**
+ * gtk_tool_button_set_icon_widget:
+ * @button: a #GtkToolButton
+ * @icon_widget: the widget used as icon, or %NULL
+ * 
+ * Sets @icon as the widget used as icon on @button. If @icon_widget is
+ * %NULL the icon is determined by the "stock_id" property. If the
+ * "stock_id" property is also %NULL, @button will not have an icon.
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_tool_button_set_icon_widget (GtkToolButton *button,
-				 GtkWidget     *icon)
+				 GtkWidget     *icon_widget)
 {
   g_return_if_fail (GTK_IS_TOOL_BUTTON (button));
-  g_return_if_fail (icon == NULL || GTK_IS_WIDGET (icon));
+  g_return_if_fail (icon_widget == NULL || GTK_IS_WIDGET (icon_widget));
 
-  if (icon != button->priv->icon_widget)
+  if (icon_widget != button->priv->icon_widget)
     {
       if (button->priv->icon_widget)
 	g_object_unref (G_OBJECT (button->priv->icon_widget));
 
-      if (icon)
+      if (icon_widget)
 	{
-	  g_object_ref (icon);
-	  gtk_object_sink (GTK_OBJECT (icon));
+	  g_object_ref (icon_widget);
+	  gtk_object_sink (GTK_OBJECT (icon_widget));
 	}
 
-      button->priv->icon_widget = icon;
+      button->priv->icon_widget = icon_widget;
 
       gtk_tool_button_construct_contents (GTK_TOOL_ITEM (button));
       
@@ -708,6 +853,19 @@ gtk_tool_button_set_icon_widget (GtkToolButton *button,
     }
 }
 
+/**
+ * gtk_tool_button_set_label_widget:
+ * @button: a #GtkToolButton
+ * @label_widget: the widget used as label, or %NULL
+ * 
+ * Sets @label_widget as the widget that will be used as the label
+ * for @button. If @label_widget is %NULL the "label" property is used
+ * as label. If "label" is also %NULL, the label in the stock item
+ * determined by the "stock_id" property is used as label. If
+ * "stock_id" is also %NULL, @button does not have a label.
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_tool_button_set_label_widget (GtkToolButton *button,
 				  GtkWidget     *label_widget)
@@ -734,6 +892,17 @@ gtk_tool_button_set_label_widget (GtkToolButton *button,
     }
 }
 
+/**
+ * gtk_tool_button_get_label_widget:
+ * @button: a #GtkToolButton
+ * 
+ * Returns the widget used as label on @button. See
+ * gtk_tool_button_set_label_widget().
+ * 
+ * Return value: The widget used as label on @button, or %NULL.
+ * 
+ * Since: 2.4
+ **/
 GtkWidget *
 gtk_tool_button_get_label_widget (GtkToolButton *button)
 {
@@ -742,6 +911,17 @@ gtk_tool_button_get_label_widget (GtkToolButton *button)
   return button->priv->label_widget;
 }
 
+/**
+ * gtk_tool_button_get_icon_widget:
+ * @button: a #GtkToolButton
+ * 
+ * Return the widget used as icon widget on @button. See
+ * gtk_tool_button_set_icon_widget().
+ * 
+ * Return value: The widget used as icon on @button, or %NULL.
+ * 
+ * Since: 2.4
+ **/
 GtkWidget *
 gtk_tool_button_get_icon_widget (GtkToolButton *button)
 {
diff --git a/gtk/gtktoolbutton.h b/gtk/gtktoolbutton.h
index afe4dec19e..591857aa43 100644
--- a/gtk/gtktoolbutton.h
+++ b/gtk/gtktoolbutton.h
@@ -78,7 +78,7 @@ void                  gtk_tool_button_set_stock_id      (GtkToolButton *button,
 							 const gchar   *stock_id);
 G_CONST_RETURN gchar *gtk_tool_button_get_stock_id      (GtkToolButton *button);
 void                  gtk_tool_button_set_icon_widget   (GtkToolButton *button,
-							 GtkWidget     *icon);
+							 GtkWidget     *icon_widget);
 GtkWidget *           gtk_tool_button_get_icon_widget   (GtkToolButton *button);
 void                  gtk_tool_button_set_label_widget  (GtkToolButton *button,
 							 GtkWidget     *label_widget);
diff --git a/gtk/gtktoolitem.c b/gtk/gtktoolitem.c
index 6f148bba6b..ca35db89bf 100644
--- a/gtk/gtktoolitem.c
+++ b/gtk/gtktoolitem.c
@@ -29,8 +29,6 @@
 
 #include <string.h>
 
-#define MENU_ID "gtk-tool-item-menu-id"
-
 enum {
   CREATE_MENU_PROXY,
   TOOLBAR_RECONFIGURED,
@@ -42,6 +40,7 @@ enum {
   PROP_0,
   PROP_VISIBLE_HORIZONTAL,
   PROP_VISIBLE_VERTICAL,
+  PROP_IS_IMPORTANT
 };
 
 struct _GtkToolItemPrivate
@@ -55,6 +54,7 @@ struct _GtkToolItemPrivate
   guint expand : 1;
   guint pack_end : 1;
   guint use_drag_window : 1;
+  guint is_important : 1;
 
   GdkWindow *drag_window;
   
@@ -161,6 +161,37 @@ gtk_tool_item_class_init (GtkToolItemClass *klass)
 							 _("Whether the toolbar item is visible when the toolbar is in a vertical orientation."),
 							 TRUE,
 							 G_PARAM_READWRITE));
+  g_object_class_install_property (object_class,
+ 				   PROP_IS_IMPORTANT,
+ 				   g_param_spec_boolean ("is_important",
+ 							 _("Is important"),
+ 							 _("Whether the toolbar item is considered important. When TRUE, toolbar buttons show text in GTK_TOOLBAR_BOTH_HORIZ mode"),
+ 							 FALSE,
+ 							 G_PARAM_READWRITE));
+
+/**
+ * GtkToolItem::create-menu-proxy:
+ * @toolitem: the object the signal was emitted on
+ *
+ * This signal is emitted when the toolbar is displaying an overflow menu.
+ * In response the tool item should either 
+ * <itemizedlist>
+ * <listitem> call gtk_tool_item_set_proxy_menu_item() with a %NULL
+ * pointer and return %TRUE to indicate that the item should not appear
+ * in the overflow menu
+ * </listitem>
+ * <listitem> call gtk_tool_item_set_proxy_menu_item() with a new menu
+ * item and return TRUE, or 
+ * </listitem>
+ * <listitem> return FALSE to indicate that the signal was not
+ * handled by the item. This means that
+ * the item will not appear in the overflow menu unless a later handler
+ * installs a menu item.
+ * </listitem>
+ * </itemizedlist>
+ * 
+ * Return value: %TRUE if the signal was handled, %FALSE if not
+ **/
   toolitem_signals[CREATE_MENU_PROXY] =
     g_signal_new ("create_menu_proxy",
 		  G_OBJECT_CLASS_TYPE (klass),
@@ -169,6 +200,23 @@ gtk_tool_item_class_init (GtkToolItemClass *klass)
 		  _gtk_boolean_handled_accumulator, NULL,
 		  _gtk_marshal_BOOLEAN__VOID,
 		  G_TYPE_BOOLEAN, 0);
+
+/**
+ * GtkToolItem::toolbar-reconfigured:
+ * @toolitem: the object the signal was emitted on
+ *
+ * This signal is emitted when some property of the toolbar that the
+ * item is a child of changes. For custom subclasses of #GtkToolItem,
+ * the default handler of this signal use the functions
+ * <itemizedlist>
+ * <listitem>gtk_toolbar_get_orientation()</listitem>
+ * <listitem>gtk_toolbar_get_style()</listitem>
+ * <listitem>gtk_toolbar_get_icon_size()</listitem>
+ * <listitem>gtk_toolbar_get_relief_style()</listitem>
+ * </itemizedlist>
+ * to find out what the toolbar should look like and change
+ * themselves accordingly.
+ **/
   toolitem_signals[TOOLBAR_RECONFIGURED] =
     g_signal_new ("toolbar_reconfigured",
 		  G_OBJECT_CLASS_TYPE (klass),
@@ -177,6 +225,14 @@ gtk_tool_item_class_init (GtkToolItemClass *klass)
 		  NULL, NULL,
 		  _gtk_marshal_VOID__VOID,
 		  G_TYPE_NONE, 0);
+/**
+ * GtkToolItem::set-tooltip:
+ * @toolitem: the object the signal was emitted on
+ *
+ * This signal is emitted when the toolitem's tooltip changes.
+ * Application developers can use gtk_tool_item_set_tooltip() to
+ * set the item's tooltip
+ **/
   toolitem_signals[SET_TOOLTIP] =
     g_signal_new ("set_tooltip",
 		  G_OBJECT_CLASS_TYPE (klass),
@@ -240,6 +296,9 @@ gtk_tool_item_set_property (GObject      *object,
     case PROP_VISIBLE_VERTICAL:
       gtk_tool_item_set_visible_horizontal (toolitem, g_value_get_boolean (value));
       break;
+    case PROP_IS_IMPORTANT:
+      gtk_tool_item_set_is_important (toolitem, g_value_get_boolean (value));
+      break;
     default:
       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
     }
@@ -261,6 +320,9 @@ gtk_tool_item_get_property (GObject    *object,
     case PROP_VISIBLE_VERTICAL:
       g_value_set_boolean (value, toolitem->priv->visible_vertical);
       break;
+    case PROP_IS_IMPORTANT:
+      g_value_set_boolean (value, toolitem->priv->is_important);
+      break;
     default:
       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
     }
@@ -409,20 +471,18 @@ gtk_tool_item_size_allocate (GtkWidget     *widget,
 static gboolean
 gtk_tool_item_create_menu_proxy (GtkToolItem *item)
 {
-  if (!GTK_BIN (item)->child)
-    {
-      GtkWidget *menu_item = NULL;
-
-      menu_item = gtk_separator_menu_item_new();
-
-      gtk_tool_item_set_proxy_menu_item (item, MENU_ID, menu_item);
-
-      return TRUE;
-    }
-  
   return FALSE;
 }
 
+/**
+ * gtk_tool_item_new:
+ * 
+ * Creates a new #GtkToolItem
+ * 
+ * Return value: the new #GtkToolItem
+ * 
+ * Since: 2.4
+ **/
 GtkToolItem *
 gtk_tool_item_new (void)
 {
@@ -433,6 +493,18 @@ gtk_tool_item_new (void)
   return item;
 }
 
+/**
+ * gtk_tool_item_get_icon_size:
+ * @tool_item: a #GtkToolItem:
+ * 
+ * Returns the icon size used for @tool_item. Custom subclasses of
+ * #GtkToolItem should call this function to find out what size icons
+ * they should use.
+ * 
+ * Return value: a #GtkIconSize indicating the icon size used for @tool_item
+ * 
+ * Since: 2.4
+ **/
 GtkIconSize
 gtk_tool_item_get_icon_size (GtkToolItem *tool_item)
 {
@@ -447,6 +519,19 @@ gtk_tool_item_get_icon_size (GtkToolItem *tool_item)
   return gtk_toolbar_get_icon_size (GTK_TOOLBAR (parent));
 }
 
+/**
+ * gtk_tool_item_get_orientation:
+ * @tool_item: a #GtkToolItem: 
+ * 
+ * Returns the orientation used for @tool_item. Custom subclasses of
+ * #GtkToolItem should call this function to find out what size icons
+ * they should use.
+ * 
+ * Return value: a #GtkOrientation indicating the orientation
+ * used for @tool_item
+ * 
+ * Since: 2.4
+ **/
 GtkOrientation
 gtk_tool_item_get_orientation (GtkToolItem *tool_item)
 {
@@ -461,6 +546,35 @@ gtk_tool_item_get_orientation (GtkToolItem *tool_item)
   return gtk_toolbar_get_orientation (GTK_TOOLBAR (parent));
 }
 
+/**
+ * gtk_tool_item_get_toolbar_style:
+ * @tool_item: a #GtkToolItem: 
+ * 
+ * Returns the toolbar style used for @tool_item. Custom subclasses of
+ * #GtkToolItem should call this function in the handler of the
+ * GtkToolItem::toolbar_reconfigured signal to find out in what style
+ * the toolbar is displayed and change themselves accordingly 
+ *
+ * Possibilities are:
+ * <itemizedlist>
+ * <listitem> GTK_TOOLBAR_BOTH, meaning the tool item should show
+ * both an icon and a label, stacked vertically </listitem>
+ * <listitem> GTK_TOOLBAR_ICONS, meaning the toolbar shows
+ * only icons </listitem>
+ * <listitem> GTK_TOOLBAR_TEXT, meaning the tool item should only
+ * show text</listitem>
+ * <listitem> GTK_TOOLBAR_BOTH_HORIZ, meaning the tool item should show
+ * both an icon and a label, arranged horizontally (however, note the 
+ * #GtkToolButton::has_text_horizontally that makes tool buttons not
+ * show labels when the toolbar style is GTK_TOOLBAR_BOTH_HORIZ.
+ * </listitem>
+ * </itemizedlist>
+ * 
+ * Return value: A #GtkToolbarStyle indicating the toolbar style used
+ * for @tool_item.
+ * 
+ * Since: 2.4
+ **/
 GtkToolbarStyle
 gtk_tool_item_get_toolbar_style (GtkToolItem *tool_item)
 {
@@ -475,6 +589,20 @@ gtk_tool_item_get_toolbar_style (GtkToolItem *tool_item)
   return gtk_toolbar_get_style (GTK_TOOLBAR (parent));
 }
 
+/**
+ * gtk_tool_item_get_relief_style:
+ * @tool_item: a #GtkToolItem: 
+ * 
+ * Returns the relief style of @tool_item. See gtk_button_set_relief_style().
+ * Custom subclasses of #GtkToolItem should call this function in the handler
+ * of the #GtkToolItem::toolbar_reconfigured signal to find out the
+ * relief style of buttons.
+ * 
+ * Return value: a #GtkReliefStyle indicating the relief style used
+ * for @tool_item.
+ * 
+ * Since: 2.4
+ **/
 GtkReliefStyle 
 gtk_tool_item_get_relief_style (GtkToolItem *tool_item)
 {
@@ -489,6 +617,18 @@ gtk_tool_item_get_relief_style (GtkToolItem *tool_item)
   return gtk_toolbar_get_relief_style (GTK_TOOLBAR (parent));
 }
 
+/**
+ * gtk_tool_item_set_expand:
+ * @tool_item: a #GtkToolItem: 
+ * @expand: Whether @tool_item is allocated extra space
+ * 
+ * Sets whether @tool_item is allocated extra space when there
+ * is more room on the toolbar then needed for the items. The
+ * effect is that the item gets bigger when the toolbar gets bigger
+ * and smaller when the toolbar gets smaller.
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_tool_item_set_expand (GtkToolItem *tool_item,
 			  gboolean     expand)
@@ -505,6 +645,17 @@ gtk_tool_item_set_expand (GtkToolItem *tool_item,
     }
 }
 
+/**
+ * gtk_tool_item_get_expand:
+ * @tool_item: a #GtkToolItem: 
+ * 
+ * Returns whether @tool_item is allocated extra space.
+ * See gtk_tool_item_set_expand().
+ * 
+ * Return value: %TRUE if @tool_item is allocated extra space.
+ * 
+ * Since: 2.4
+ **/
 gboolean
 gtk_tool_item_get_expand (GtkToolItem *tool_item)
 {
@@ -513,6 +664,17 @@ gtk_tool_item_get_expand (GtkToolItem *tool_item)
   return tool_item->priv->expand;
 }
 
+/**
+ * gtk_tool_item_set_pack_end:
+ * @tool_item: a #GtkToolItem: 
+ * @pack_end: whether @tool_item is allocated at the end of the toolbar.
+ * 
+ * Sets whether @tool_item is allocated at the end of the toolbar. This is
+ * useful for #GtkToolItem<!-- -->s that are used as "throbbers" in
+ * web-browser-type applications.
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_tool_item_set_pack_end (GtkToolItem *tool_item,
 			    gboolean     pack_end)
@@ -529,6 +691,17 @@ gtk_tool_item_set_pack_end (GtkToolItem *tool_item,
     }
 }
 
+/**
+ * gtk_tool_item_get_pack_end:
+ * @tool_item: a #GtkToolItem: 
+ * 
+ * Returns whether @tool_item is packed at the end of the toolbar.
+ * See gtk_tool_item_set_pack_end().
+ * 
+ * Return value: %TRUE if @tool_item is packed at the end of the toolbar.
+ * 
+ * Since: 2.4
+ **/
 gboolean
 gtk_tool_item_get_pack_end (GtkToolItem *tool_item)
 {
@@ -537,6 +710,17 @@ gtk_tool_item_get_pack_end (GtkToolItem *tool_item)
   return tool_item->priv->pack_end;
 }
 
+/**
+ * gtk_tool_item_set_homogeneous:
+ * @tool_item: a #GtkToolItem: 
+ * @homogeneous: whether @tool_item is the same size as other homogeneous items
+ * 
+ * Sets whether @tool_item is to be allocated the same size as other
+ * homogeneous items. The effect is that all homogeneous items will have
+ * the same width as the widest of the items.
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_tool_item_set_homogeneous (GtkToolItem *tool_item,
 			       gboolean     homogeneous)
@@ -553,6 +737,18 @@ gtk_tool_item_set_homogeneous (GtkToolItem *tool_item,
     }
 }
 
+/**
+ * gtk_tool_item_get_homogeneous:
+ * @tool_item: a #GtkToolItem: 
+ * 
+ * Returns whether @tool_item is the same size as other homogeneous
+ * items. See gtk_tool_item_set_homogeneous().
+ * 
+ * Return value: %TRUE if the item is the same size as other homogeneous
+ * item.s
+ * 
+ * Since: 2.4
+ **/
 gboolean
 gtk_tool_item_get_homogeneous (GtkToolItem *tool_item)
 {
@@ -561,6 +757,55 @@ gtk_tool_item_get_homogeneous (GtkToolItem *tool_item)
   return tool_item->priv->homogeneous;
 }
 
+/**
+ * gtk_tool_item_get_is_important:
+ * @tool_item: a #GtkToolItem
+ * 
+ * Returns whether @tool_item is considered important. See
+ * gtk_tool_item_set_ismportant()
+ * 
+ * Return value: %TRUE if @tool_item is considered important.
+ * 
+ * Since: 2.4
+ **/
+gboolean
+gtk_tool_item_get_is_important (GtkToolItem *tool_item)
+{
+  g_return_val_if_fail (GTK_IS_TOOL_ITEM (tool_item), FALSE);
+
+  return tool_item->priv->is_important;
+}
+
+/**
+ * gtk_tool_item_set_is_important:
+ * @tool_item: a #GtkToolItem
+ * @is_imporatnt: whether the tool item should be considered important
+ * 
+ * Sets whether @tool_item should be considered important. The #GtkToolButton
+ * class uses this property to determine whether to show or hide its label
+ * when the toolbar style is %GTK_TOOLBAR_BOTH_HORIZ. The result is that
+ * only tool buttons with the "is_important" property set have labels, and
+ * effect known as "priority text"
+ * 
+ * Since: 2.4
+ **/
+void
+gtk_tool_item_set_is_important (GtkToolItem *tool_item, gboolean is_important)
+{
+  g_return_if_fail (GTK_IS_TOOL_ITEM (tool_item));
+
+  is_important = is_important != FALSE;
+
+  if (is_important != tool_item->priv->is_important)
+    {
+      tool_item->priv->is_important = is_important;
+
+      gtk_widget_queue_resize (GTK_WIDGET (tool_item));
+
+      g_object_notify (G_OBJECT (tool_item), "is_important");
+    }
+}
+
 static gboolean
 gtk_tool_item_real_set_tooltip (GtkToolItem *tool_item,
 				GtkTooltips *tooltips,
@@ -577,6 +822,19 @@ gtk_tool_item_real_set_tooltip (GtkToolItem *tool_item,
   return TRUE;
 }
 
+/**
+ * gtk_tool_item_set_tooltip:
+ * @tool_item: a #GtkToolItem: 
+ * @tooltips: The #GtkTooltips object to be used
+ * @tip_text: text to be used as tooltip text for @tool_item
+ * @tip_private: text to be used as rpivate tooltip text
+ *
+ * Sets the #GtkTooltips object to be used for @tool_item, the
+ * text to be displayed as tooltip on the item and the private text
+ * to be used. See gtk_tooltips_set_tip().
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_tool_item_set_tooltip (GtkToolItem *tool_item,
 			   GtkTooltips *tooltips,
@@ -591,6 +849,18 @@ gtk_tool_item_set_tooltip (GtkToolItem *tool_item,
 		 tooltips, tip_text, tip_private, &retval);
 }
 
+/**
+ * gtk_tool_item_set_use_drag_window:
+ * @toolitem: a #GtkToolItem 
+ * @use_drag_window: Whether @toolitem has a drag window.
+ * 
+ * Sets whether @toolitem has a drag window. When %TRUE the
+ * toolitem can be used as a drag source through gtk_drag_source_set().
+ * When @toolitem has a drag window it will intercept all events,
+ * even those that would otherwise be sent to a child of @toolitem.
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_tool_item_set_use_drag_window (GtkToolItem *toolitem,
 				   gboolean     use_drag_window)
@@ -619,6 +889,17 @@ gtk_tool_item_set_use_drag_window (GtkToolItem *toolitem,
     }
 }
 
+/**
+ * gtk_tool_item_get_use_drag_window:
+ * @toolitem: a #GtkToolItem 
+ * 
+ * Returns whether @toolitem has a drag window. See
+ * gtk_tool_item_set_use_drag_window().
+ * 
+ * Return value: %TRUE if @toolitem uses a drag window.
+ * 
+ * Since: 2.4
+ **/
 gboolean
 gtk_tool_item_get_use_drag_window (GtkToolItem *toolitem)
 {
@@ -627,6 +908,15 @@ gtk_tool_item_get_use_drag_window (GtkToolItem *toolitem)
   return toolitem->priv->use_drag_window;
 }
 
+/**
+ * gtk_tool_item_set_visible_horizontal:
+ * @toolitem: a #GtkToolItem
+ * @visible_horizontal: Whether @toolitem is visible when in horizontal mode
+ * 
+ * Sets whether @toolitem is visible when 
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_tool_item_set_visible_horizontal (GtkToolItem *toolitem,
 				      gboolean     visible_horizontal)
@@ -645,6 +935,18 @@ gtk_tool_item_set_visible_horizontal (GtkToolItem *toolitem,
     }
 }
 
+/**
+ * gtk_tool_item_get_visible_horizontal:
+ * @toolitem: a #GtkToolItem 
+ * 
+ * Returns whether the @toolitem is visible on toolbars that are
+ * docked horizontally
+ * 
+ * Return value: %TRUE if @toolitem is visible on toolbars that are
+ * docked horizontally.
+ * 
+ * Since: 2.4
+ **/
 gboolean
 gtk_tool_item_get_visible_horizontal (GtkToolItem *toolitem)
 {
@@ -653,6 +955,19 @@ gtk_tool_item_get_visible_horizontal (GtkToolItem *toolitem)
   return toolitem->priv->visible_horizontal;
 }
 
+/**
+ * gtk_tool_item_set_visible_vertical:
+ * @toolitem: a #GtkToolItem 
+ * @visible_vertical: whether @toolitem is visible when the toolbar
+ * is in vertical mode
+ *
+ * Sets whether @toolitem is visible when the toolbar is docked
+ * vertically. Some tool items, such as text entries, are too wide to be
+ * useful on a vertically docked toolbar. If @visible_vertical is %FALSE
+ * @toolitem will not appear on toolbars that are docked vertically.
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_tool_item_set_visible_vertical (GtkToolItem *toolitem,
 				    gboolean     visible_vertical)
@@ -671,6 +986,17 @@ gtk_tool_item_set_visible_vertical (GtkToolItem *toolitem,
     }
 }
 
+/**
+ * gtk_tool_item_get_visible_vertical:
+ * @toolitem: a #GtkToolItem 
+ * 
+ * Returns whether @toolitem is visible when the toolbar is docked vertically.
+ * See gtk_tool_item_set_visible_vertical().
+ * 
+ * Return value: Whether @toolitem is visible when the toolbar is docked vertically
+ * 
+ * Since: 2.4
+ **/
 gboolean
 gtk_tool_item_get_visible_vertical (GtkToolItem *toolitem)
 {
@@ -679,6 +1005,19 @@ gtk_tool_item_get_visible_vertical (GtkToolItem *toolitem)
   return toolitem->priv->visible_vertical;
 }
 
+/**
+ * gtk_tool_item_retrieve_proxy_menu_item:
+ * @tool_item: a #GtkToolItem: 
+ * 
+ * Returns the #GtkMenuItem that was last set by
+ * gtk_tool_item_set_proxy_menu_item(), ie. the #GtkMenuItem
+ * that is going to appear in the overflow menu.
+ * 
+ * Return value: The #GtkMenuItem that is going to appear in the
+ * overflow menu for @tool_item.
+ * 
+ * Since: 2.4
+ **/
 GtkWidget *
 gtk_tool_item_retrieve_proxy_menu_item (GtkToolItem *tool_item)
 {
@@ -691,6 +1030,24 @@ gtk_tool_item_retrieve_proxy_menu_item (GtkToolItem *tool_item)
   return tool_item->priv->menu_item;
 }
 
+/**
+ * gtk_tool_item_get_proxy_menu_item:
+ * @tool_item: a #GtkToolItem: 
+ * @menu_item_id: a string used to identify the menu item
+ * 
+ * If @menu_item_id matches the string passed to
+ * gtk_tool_item_set_proxy_menu_item() return the corresponding #GtkMenuItem.
+ *
+ * Custom subclasses of #GtkToolItem should use this function to update
+ * their menu item when the #GtkToolItem changes. That the
+ * @menu_item_id<!-- -->s must match ensures that a #GtkToolItem will not
+ * inadvertently change a menu item that they did not create.
+ * 
+ * Return value: The #GtkMenuItem passed to
+ * gtk_tool_item_set_proxy_menu_item(), if the @menu_item_id<!-- -->s match.
+ * 
+ * Since: 2.4
+ **/
 GtkWidget *
 gtk_tool_item_get_proxy_menu_item (GtkToolItem *tool_item,
 				   const gchar *menu_item_id)
@@ -704,6 +1061,18 @@ gtk_tool_item_get_proxy_menu_item (GtkToolItem *tool_item,
   return NULL;
 }
 
+/**
+ * gtk_tool_item_set_proxy_menu_item:
+ * @tool_item: a #GtkToolItem:
+ * @menu_item_id: a string used to identify @menu_item
+ * @menu_item: a #GtkMenuItem to be used in the overflow menu
+ * 
+ * Sets the #GtkMenuItem used in the toolbar overflow menu. The
+ * @menu_item_id is used to identify the caller of this function and
+ * should also be used with gtk_tool_item_get_proxy_menu_item().
+ * 
+ * Since: 2.4
+ **/
 void
 gtk_tool_item_set_proxy_menu_item (GtkToolItem *tool_item,
 				   const gchar *menu_item_id,
@@ -733,6 +1102,16 @@ gtk_tool_item_set_proxy_menu_item (GtkToolItem *tool_item,
     }
 }
 
+/**
+ * _gtk_tool_item_toolbar_reconfigured:
+ * @tool_item: a #GtkToolItem: 
+ * 
+ * Emits the signal #GtkToolItem::toolbar_reconfigured on @tool_item. This
+ * internal function is called by #GtkToolbar when some aspect of its
+ * configuration changes.
+ * 
+ * Since: 2.4
+ **/
 void
 _gtk_tool_item_toolbar_reconfigured (GtkToolItem *tool_item)
 {
diff --git a/gtk/gtktoolitem.h b/gtk/gtktoolitem.h
index 4811869643..ea5d4c642a 100644
--- a/gtk/gtktoolitem.h
+++ b/gtk/gtktoolitem.h
@@ -71,7 +71,7 @@ GtkToolItem *gtk_tool_item_new      (void);
 
 void            gtk_tool_item_set_homogeneous          (GtkToolItem *tool_item,
 							gboolean     homogeneous);
-gboolean	gtk_tool_item_get_homogeneous          (GtkToolItem *tool_item);
+gboolean        gtk_tool_item_get_homogeneous          (GtkToolItem *tool_item);
 
 void            gtk_tool_item_set_expand               (GtkToolItem *tool_item,
 							gboolean     expand);
@@ -95,9 +95,13 @@ void            gtk_tool_item_set_visible_horizontal   (GtkToolItem *toolitem,
 gboolean        gtk_tool_item_get_visible_horizontal   (GtkToolItem *toolitem);
 
 void            gtk_tool_item_set_visible_vertical     (GtkToolItem *toolitem,
-							gboolean     visible_horizontal);
+							gboolean     visible_vertical);
 gboolean        gtk_tool_item_get_visible_vertical     (GtkToolItem *toolitem);
 
+gboolean        gtk_tool_item_get_is_important         (GtkToolItem *tool_item);
+void            gtk_tool_item_set_is_important         (GtkToolItem *tool_item,
+							gboolean     is_important);
+
 GtkIconSize     gtk_tool_item_get_icon_size            (GtkToolItem *tool_item);
 GtkOrientation  gtk_tool_item_get_orientation          (GtkToolItem *tool_item);
 GtkToolbarStyle gtk_tool_item_get_toolbar_style        (GtkToolItem *tool_item);