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

1 files changed, 10 insertions, 4 deletions

diff --git a/gtk/gtktoolbar.c b/gtk/gtktoolbar.c
index 4973be40c0..b62e58036f 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.
  *
@@ -2639,10 +2644,11 @@ gtk_toolbar_get_icon_size (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
  **/