[gtk+/gtk-3-16] docs: Improve deprecation notices for GtkSettings

[Matthias Clasen <matthiasc src gnome org>]

commit 13b84cd35f4fe755b1568eb015cf5015b06b9114
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Wed Jun 10 17:16:41 2015 +0100

    docs: Improve deprecation notices for GtkSettings
    
    The button and menu item icons settings are deprecated; application
    developers should control whether or not a widget should show an icon,
    using the existing API.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=750718

 gtk/gtksettings.c |   12 ++++++++++--
 1 files changed, 10 insertions(+), 2 deletions(-)
---
diff --git a/gtk/gtksettings.c b/gtk/gtksettings.c
index 2356715..cbafb27 100644
--- a/gtk/gtksettings.c
+++ b/gtk/gtksettings.c
@@ -1312,7 +1312,11 @@ gtk_settings_class_init (GtkSettingsClass *class)
    *
    * Since: 2.4
    *
-   * Deprecated: 3.10: This setting is deprecated
+   * Deprecated: 3.10: This setting is deprecated. Application developers
+   *   control whether a button should show an icon or now, on a
+   *   per-button basis. If a #GtkButton should show an icon, use the
+   *   #GtkButton:always-show-image property of #GtkButton, and pack a
+   *   #GtkImage inside the #GtkButton
    */
   result = settings_install_property_parser (class,
                                              g_param_spec_boolean ("gtk-button-images",
@@ -1356,7 +1360,11 @@ gtk_settings_class_init (GtkSettingsClass *class)
    *
    * Whether images should be shown in menu items
    *
-   * Deprecated: 3.10: This setting is deprecated
+   * Deprecated: 3.10: This setting is deprecated. Application developers
+   *   control whether or not a #GtkMenuItem should have an icon or not,
+   *   on a per widget basis. Either use a #GtkMenuItem with a #GtkBox
+   *   containing a #GtkImage and a #GtkAccelLabel, or describe your menus
+   *   using a #GMenu XML description
    */
   result = settings_install_property_parser (class,
                                              g_param_spec_boolean ("gtk-menu-images",