From e46ac4dcba721bfaa2449e900f3a2b3ad043cd11 Mon Sep 17 00:00:00 2001
From: Daniel Boles <dboles@src.gnome.org>
Date: Wed, 4 Oct 2017 10:14:42 +0100
Subject: [PATCH] ComboBox: Clarify :row|column-span/wrap-width docs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ComboBox warned in the doc for :row-span-column that the value must not
exceed :wrap-width, but :wrap-width does not interact with the number of
rows; it’s the :column-span-column that’s relevant.

Also: Warn that spans must be > 0 for rows too, & that column spans <=
:wrap-width are also not useful for items at menu column positions > 0.
Rrefer to items having spans, not values, as we’re already talking about
values in the model (& rows in the menu). And clarify :wrap-width a bit.
---
 gtk/gtkcombobox.c | 25 +++++++++++--------------
 1 file changed, 11 insertions(+), 14 deletions(-)

diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index e3b1486cb2..a4867efe6f 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -728,9 +728,8 @@ gtk_combo_box_class_init (GtkComboBoxClass *klass)
   /**
    * GtkComboBox:wrap-width:
    *
-   * If wrap-width is set to a positive value, the list will be
-   * displayed in multiple columns, the number of columns is
-   * determined by wrap-width.
+   * If wrap-width is set to a positive value, items in the popup will be laid
+   * out along multiple columns, starting a new row on reaching the wrap width.
    *
    * Since: 2.4
    */
@@ -748,12 +747,10 @@ gtk_combo_box_class_init (GtkComboBoxClass *klass)
   /**
    * GtkComboBox:row-span-column:
    *
-   * If this is set to a non-negative value, it must be the index of a column 
-   * of type %G_TYPE_INT in the model. 
-   *
-   * The values of that column are used to determine how many rows a value in 
-   * the list will span. Therefore, the values in the model column pointed to 
-   * by this property must be greater than zero and not larger than wrap-width.
+   * If this is set to a non-negative value, it must be the index of a column
+   * of type %G_TYPE_INT in the model. The value in that column for each item
+   * will determine how many rows that item will span in the popup. Therefore,
+   * values in this column must be greater than zero.
    *
    * Since: 2.4
    */
@@ -771,11 +768,11 @@ gtk_combo_box_class_init (GtkComboBoxClass *klass)
   /**
    * GtkComboBox:column-span-column:
    *
-   * If this is set to a non-negative value, it must be the index of a column 
-   * of type %G_TYPE_INT in the model. 
-   *
-   * The values of that column are used to determine how many columns a value 
-   * in the list will span. 
+   * If this is set to a non-negative value, it must be the index of a column
+   * of type %G_TYPE_INT in the model. The value in that column for each item
+   * will determine how many columns that item will span in the popup.
+   * Therefore, values in this column must be greater than zero, and the sum of
+   * an item’s column position + span should not exceed #GtkComboBox:wrap-width.
    *
    * Since: 2.4
    */