[gtk+] docs: Reword the deprecation notice for gtk_widget_override_*

[Emmanuele Bassi <ebassi src gnome org>]

commit 6950116678f332dc88d765f0e9c2325735e28137
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sun Mar 8 14:39:18 2015 +0000

    docs: Reword the deprecation notice for gtk_widget_override_*
    
    They are a bit terse, and they should point to the preferred way of
    overriding the theme, i.e. using a GtkStyleProvider for your
    application, and custom style classes.

 gtk/gtkwidget.c |   22 ++++++++++++++++++----
 1 files changed, 18 insertions(+), 4 deletions(-)
---
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index d9c2a9c..0e9ed82 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -9685,7 +9685,12 @@ gtk_widget_override_color (GtkWidget     *widget,
  *
  * Since: 3.0
  *
- * Deprecated:3.16: Use a custom style provider and style classes instead
+ * Deprecated: 3.16: This function is not useful in the context of CSS-based
+ *   rendering. If you wish to change the way a widget renders its background
+ *   you should use a custom CSS style, through an application-specific
+ *   #GtkStyleProvider and a CSS style class. You can also override the default
+ *   drawing of a widget through the #GtkWidget::draw signal, and use Cairo to
+ *   draw a specific color, regardless of the CSS style.
  */
 void
 gtk_widget_override_background_color (GtkWidget     *widget,
@@ -9711,7 +9716,10 @@ gtk_widget_override_background_color (GtkWidget     *widget,
  *
  * Since: 3.0
  *
- * Deprecated:3.16: Use a custom style provider and style classes instead
+ * Deprecated: 3.16: This function is not useful in the context of CSS-based
+ *   rendering. If you wish to change the font a widget uses to render its text
+ *   you should use a custom CSS style, through an application-specific
+ *   #GtkStyleProvider and a CSS style class.
  */
 void
 gtk_widget_override_font (GtkWidget                  *widget,
@@ -9741,7 +9749,10 @@ gtk_widget_override_font (GtkWidget                  *widget,
  *
  * Since: 3.0
  *
- * Deprecated:3.16: Use a custom style provider and style classes instead
+ * Deprecated: 3.16: This function is not useful in the context of CSS-based
+ *   rendering. If you wish to change the color used to render symbolic icons
+ *   you should use a custom CSS style, through an application-specific
+ *   #GtkStyleProvider and a CSS style class.
  */
 void
 gtk_widget_override_symbolic_color (GtkWidget     *widget,
@@ -9776,7 +9787,10 @@ gtk_widget_override_symbolic_color (GtkWidget     *widget,
  *
  * Since: 3.0
  *
- * Deprecated:3.16: Use a custom style provider and style classes instead
+ * Deprecated: 3.16: This function is not useful in the context of CSS-based
+ *   rendering. If you wish to change the color used to render the primary
+ *   and seconday cursors you should use a custom CSS style, through an
+ *   application-specific #GtkStyleProvider and a CSS style class.
  */
 void
 gtk_widget_override_cursor (GtkWidget     *widget,