[gtk+/gtk-3-22] Toolbar: Clarify how the arrow overflow menu works

[Daniel Boles <dboles src gnome org>]

commit 66d63e4a4702df0f340179dc847fae19e49ddab8
Author: Daniel Boles <dboles src gnome org>
Date:   Sun Sep 3 10:41:56 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

 gtk/gtktoolbar.c |   14 ++++++++++----
 1 files changed, 10 insertions(+), 4 deletions(-)
---
diff --git a/gtk/gtktoolbar.c b/gtk/gtktoolbar.c
index 80efa51..7acad14 100644
--- a/gtk/gtktoolbar.c
+++ b/gtk/gtktoolbar.c
@@ -80,6 +80,11 @@
  * “expand” is #TRUE and the property #GtkSeparatorToolItem:draw is set to
  * #FALSE, the effect is to force all following items to the end of the toolbar.
  *
+ * 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.
+ *
  * Creating a context menu for the toolbar can be done by connecting to
  * the #GtkToolbar::popup-context-menu signal.
  *
@@ -2980,10 +2985,11 @@ 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.
  * 
  * Since: 2.4
  **/