[gtk+/gtk-2-24] ComboBox: Clarify :row|column-span/wrap-width docs

[Daniel Boles <dboles src gnome org>]

commit e46ac4dcba721bfaa2449e900f3a2b3ad043cd11
Author: Daniel Boles <dboles src gnome org>
Date:   Wed Oct 4 10:14:42 2017 +0100

    ComboBox: Clarify :row|column-span/wrap-width docs
    
    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 files changed, 11 insertions(+), 14 deletions(-)
---
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index e3b1486..a4867ef 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
    */