[gtk+/gtk-2-24] Toolbar: Clarify how the arrow overflow menu works

[Daniel Boles <dboles src gnome org>]

commit d57d105e110fe3706bba92b687c260a13fac27b0
Author: Daniel Boles <dboles src gnome org>
Date:   Sun Sep 3 11:22:58 2017 +0100

    Toolbar: Clarify how the arrow overflow menu works
    
    The fact it affects the preferred size, and only works with ToolItems
    that return a menu proxy item, was unclear unless deduced from other
    sources, and this led to users thinking it was broken, for example:
    
    https://stackoverflow.com/q/44644642/2757035
    
    https://bugzilla.gnome.org/show_bug.cgi?id=787158
    https://bugzilla.gnome.org/show_bug.cgi?id=787195

 docs/reference/gtk/tmpl/gtktoolbar.sgml |    6 ++++++
 gtk/gtktoolbar.c                        |   10 ++++++----
 2 files changed, 12 insertions(+), 4 deletions(-)
---
diff --git a/docs/reference/gtk/tmpl/gtktoolbar.sgml b/docs/reference/gtk/tmpl/gtktoolbar.sgml
index 939566b..80bec92 100644
--- a/docs/reference/gtk/tmpl/gtktoolbar.sgml
+++ b/docs/reference/gtk/tmpl/gtktoolbar.sgml
@@ -22,6 +22,12 @@ the "expand" property set to #TRUE and the "draw" property set to
 toolbar.
 </para>
 <para>
+By default, a toolbar can be shrunk, upon which it will add an arrow button
+to show an overflow menu offering access to any #GtkToolItem child that has
+a proxy menu item. To disable this and request enough size for all children,
+call gtk_toolbar_set_show_arrow() to set #GtkToolbar:show-arrow to %FALSE.
+</para>
+<para>
 Creating a context menu for the toolbar can be done by connecting to
 the #GtkToolbar::popup-context-menu signal.
 </para>
diff --git a/gtk/gtktoolbar.c b/gtk/gtktoolbar.c
index b2c4b15..f774dfa 100644
--- a/gtk/gtktoolbar.c
+++ b/gtk/gtktoolbar.c
@@ -3074,10 +3074,12 @@ gtk_toolbar_get_relief_style (GtkToolbar *toolbar)
  * @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.
+ * Sets whether to show an overflow menu when @toolbar isn’t allocated enough
+ * size to show all of its items. If %TRUE, items which can’t fit in @toolbar,
+ * and which have a proxy menu item set by gtk_tool_item_set_proxy_menu_item()
+ * or #GtkToolItem::create-menu-proxy, will be available in an overflow menu,
+ * which can be opened by an added arrow button. If %FALSE, @toolbar will
+ * request enough size to fit all of its child items without any overflow.
  * 
  * Since: 2.4
  **/