[gtk+] gdkwindow: Add some extra documentation to gdk_cairo_create

[Jasper St. Pierre <jstpierre src gnome org>]

commit ec5e913a9b525f04541b9d06e7c49dfa8f6a0ce0
Author: Jasper St. Pierre <jstpierre mecheye net>
Date:   Sat Jun 21 09:58:20 2014 -0400

    gdkwindow: Add some extra documentation to gdk_cairo_create
    
    Mention the need to wrap the function inside
    gdk_window_begin_paint_region and gdk_window_end_paint.

 gdk/gdkwindow.c |    5 +++++
 1 files changed, 5 insertions(+), 0 deletions(-)
---
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index 36d01e4..fcb4cdb 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -3030,6 +3030,11 @@ _gdk_window_ref_cairo_surface (GdkWindow *window)
  * Note that calling cairo_reset_clip() on the resulting #cairo_t will
  * produce undefined results, so avoid it at all costs.
  *
+ * As of GTK+ 3.14, you need to wrap calls to this function with
+ * gdk_window_begin_paint_region() / gdk_window_begin_paint_rect() and
+ * gdk_window_end_paint(). Calling it outside of a "paint" will
+ * result in a warning printed and a dummy surface being returned.
+ *
  * Returns: A newly created Cairo context. Free with
  *  cairo_destroy() when you are done drawing.
  *