[gtk+] ComboBox|TreeMenu: Clarify :row|column-span-column

[Daniel Boles <dboles src gnome org>]

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

    ComboBox|TreeMenu: Clarify :row|column-span-column
    
    ComboBox and TreeMenu 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, and that column spans <=
    :wrap-width are also not useful for items at menu column positions > 0.
    
    Finally, refer to items having spans, not values, as we were already
    talking about values in the model (and rows in the menu).

 gtk/gtkcombobox.c |   16 +++++++---------
 gtk/gtktreemenu.c |   15 ++++++++-------
 2 files changed, 15 insertions(+), 16 deletions(-)
---
diff --git a/gtk/gtkcombobox.c b/gtk/gtkcombobox.c
index 633099d..5937c2c 100644
--- a/gtk/gtkcombobox.c
+++ b/gtk/gtkcombobox.c
@@ -687,11 +687,9 @@ 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.
+   * of type %G_TYPE_INT in the model. The value in that column for each item
+   * will determine how many rows the item will span in the popup. Therefore,
+   * values in this column must be greater than zero.
    *
    * Since: 2.4
    */
@@ -710,10 +708,10 @@ 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.
+   * 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
    */
diff --git a/gtk/gtktreemenu.c b/gtk/gtktreemenu.c
index afc90bd..c62b5df 100644
--- a/gtk/gtktreemenu.c
+++ b/gtk/gtktreemenu.c
@@ -318,11 +318,9 @@ _gtk_tree_menu_class_init (GtkTreeMenuClass *class)
    * GtkTreeMenu: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.
+   * 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: 3.0
    */
@@ -342,8 +340,11 @@ _gtk_tree_menu_class_init (GtkTreeMenuClass *class)
    * 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 #GtkTreeMenu:wrap-width.
    *
    * Since: 3.0
    */