[gtk+/gtk-3-16] widget: Clarify docs on gtk_widget_set_double_buffered()

[Matthias Clasen <matthiasc src gnome org>]

commit 2cf5eddcebd4dce73f0fc3e83020f5dec84e9ac9
Author: Benjamin Otte <otte redhat com>
Date:   Mon Jun 8 20:28:10 2015 +0200

    widget: Clarify docs on gtk_widget_set_double_buffered()
    
    Also make them more scary so people really really don't use it as a
    random knob when trying to make things go fast.
    
    //bugzilla.gnome.org/show_bug.cgi?id=750505

 gtk/gtkwidget.c |   15 ++++++++++-----
 1 files changed, 10 insertions(+), 5 deletions(-)
---
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 2da2919..bb380d9 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -9310,11 +9310,16 @@ gtk_widget_get_app_paintable (GtkWidget *widget)
  * pixmap will not happen automatically (as it is done in
  * gdk_window_begin_paint_region()).
  *
- * Since 3.10 this function only works for widgets with native
- * windows.
- *
- * Deprecated: 3.14: This does not work under non-X11 backends,
- * and it should not be used in newly written code.
+ * In 3.10 GTK and GDK have been restructured for translucent drawing. Since
+ * then expose events for double-buffered widgets are culled into a single
+ * event to the toplevel GDK window. If you now unset double buffering, you
+ * will cause a separate rendering pass for every widget. This will likely
+ * cause rendering problems - in particular related to stacking - and usually
+ * increases rrendering times significantly.
+ *
+ * Deprecated: 3.14: This function does not work under non-X11 backends or with
+ * non-native windows.
+ * It should not be used in newly written code.
  **/
 void
 gtk_widget_set_double_buffered (GtkWidget *widget,