[gtk+] icontheme: Clarify GENERIC_FALLBACK flag handling

[Benjamin Otte <otte src gnome org>]

commit 8ec2362d81db40e5587cd269eb932d15d381b6d1
Author: Benjamin Otte <otte redhat com>
Date:   Fri Oct 9 15:41:00 2015 +0200

    icontheme: Clarify GENERIC_FALLBACK flag handling
    
    - Add docs explaining that it doesn't work everywhere
    - g_warn_if_fail() in the APIs where it doesn't work

 gtk/gtkicontheme.c |    3 +++
 gtk/gtkicontheme.h |    3 ++-
 2 files changed, 5 insertions(+), 1 deletions(-)
---
diff --git a/gtk/gtkicontheme.c b/gtk/gtkicontheme.c
index 59e99fc..eb89bf4 100644
--- a/gtk/gtkicontheme.c
+++ b/gtk/gtkicontheme.c
@@ -2155,6 +2155,7 @@ gtk_icon_theme_choose_icon (GtkIconTheme       *icon_theme,
   g_return_val_if_fail (icon_names != NULL, NULL);
   g_return_val_if_fail ((flags & GTK_ICON_LOOKUP_NO_SVG) == 0 ||
                         (flags & GTK_ICON_LOOKUP_FORCE_SVG) == 0, NULL);
+  g_warn_if_fail ((flags & GTK_ICON_LOOKUP_GENERIC_FALLBACK) == 0);
 
   return choose_icon (icon_theme, icon_names, size, 1, flags);
 }
@@ -2196,6 +2197,7 @@ gtk_icon_theme_choose_icon_for_scale (GtkIconTheme       *icon_theme,
   g_return_val_if_fail ((flags & GTK_ICON_LOOKUP_NO_SVG) == 0 ||
                         (flags & GTK_ICON_LOOKUP_FORCE_SVG) == 0, NULL);
   g_return_val_if_fail (scale >= 1, NULL);
+  g_warn_if_fail ((flags & GTK_ICON_LOOKUP_GENERIC_FALLBACK) == 0);
 
   return choose_icon (icon_theme, icon_names, size, scale, flags);
 }
@@ -5423,6 +5425,7 @@ gtk_icon_theme_lookup_by_gicon_for_scale (GtkIconTheme       *icon_theme,
 
   g_return_val_if_fail (GTK_IS_ICON_THEME (icon_theme), NULL);
   g_return_val_if_fail (G_IS_ICON (icon), NULL);
+  g_warn_if_fail ((flags & GTK_ICON_LOOKUP_GENERIC_FALLBACK) == 0);
 
   if (GDK_IS_PIXBUF (icon))
     {
diff --git a/gtk/gtkicontheme.h b/gtk/gtkicontheme.h
index e57c95c..7824a46 100644
--- a/gtk/gtkicontheme.h
+++ b/gtk/gtkicontheme.h
@@ -109,7 +109,8 @@ struct _GtkIconThemeClass
  *   as well as files. For a builtin icon, gtk_icon_info_get_filename()
  *   is %NULL and you need to call gtk_icon_info_get_builtin_pixbuf().
  * @GTK_ICON_LOOKUP_GENERIC_FALLBACK: Try to shorten icon name at '-'
- *   characters before looking at inherited themes. For more general
+ *   characters before looking at inherited themes. This flag is only
+ *   supported in functions that take a single icon name. For more general
  *   fallback, see gtk_icon_theme_choose_icon(). Since 2.12.
  * @GTK_ICON_LOOKUP_FORCE_SIZE: Always get the icon scaled to the
  *   requested size. Since 2.14.