[gtk+] docs: Improve gdk_window_create_similar_image_surface()

[Emmanuele Bassi <ebassi src gnome org>]

commit b5a2bba84071265ffd2c2327e710b8bee3318ea4
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Mon Jul 11 16:55:10 2016 +0100

    docs: Improve gdk_window_create_similar_image_surface()
    
    The sizes passed are in device pixels and do not take into account the
    scaling factor of the window itself. We cannot change the semantics of
    the function, so let's at least add a warning for this trap door.

 gdk/gdkwindow.c |   19 +++++++++++++++++++
 1 files changed, 19 insertions(+), 0 deletions(-)
---
diff --git a/gdk/gdkwindow.c b/gdk/gdkwindow.c
index b9c5843..5e91fcc 100644
--- a/gdk/gdkwindow.c
+++ b/gdk/gdkwindow.c
@@ -10046,6 +10046,25 @@ gdk_window_create_similar_surface (GdkWindow *     window,
  * Initially the surface contents are all 0 (transparent if contents
  * have transparency, black otherwise.)
  *
+ * The @width and @height of the new surface are not affected by
+ * the scaling factor of the @window, or by the @scale argument; they
+ * are the size of the surface in device pixels. If you wish to create
+ * an image surface capable of holding the contents of @window you can
+ * use:
+ *
+ * |[<!-- language="C" -->
+ *   int scale = gdk_window_get_scale_factor (window);
+ *   int width = gdk_window_get_width (window) * scale;
+ *   int height = gdk_window_get_height (window) * scale;
+ *
+ *   // format is set elsewhere
+ *   cairo_surface_t *surface =
+ *     gdk_window_create_similar_image_surface (window,
+ *                                              format,
+ *                                              width, height,
+ *                                              scale);
+ * ]|
+ *
  * Returns: a pointer to the newly allocated surface. The caller
  * owns the surface and should call cairo_surface_destroy() when done
  * with it.