API: Remove gdk_cairo_reset_clip()

You should not ever ever ever call cairo_reset_clip(). If you do, your
code is broken and you deserve everything you get.
And we should definitely not support this insanity.

docs/reference/gdk/gdk3-sections.txt

@@ -616,7 +616,6 @@ gdk_cairo_set_source_pixbuf
 gdk_cairo_set_source_window
 gdk_cairo_rectangle
 gdk_cairo_region
-gdk_cairo_reset_clip
 gdk_cairo_region_create_from_surface
 </SECTION>
 

docs/reference/gtk/migrating-ClientSideWindows.sgml

@@ -46,15 +46,9 @@
 
   <para>
     Problems can also occur when using cairo for drawing. One thing that can
-    go wrong is clip handling. If you ever need to reset the clip region on
-    a cairo_t (i.e. use cairo_reset_clip()), you have to to use
-    gdk_cairo_reset_clip() instead. The reason for this is that the cairo_reset_clip() call will remove the initial clip region that limits your drawing to
-    the client-side window at hand, so you will end up drawing over stuff
-    outside the window. You also need to use gdk_cairo_reset_clip() if you
-    use a cairo_t that was not allocated in a double-buffered expose handler
-    and keep it in use after window hierarchy changes (resizing, moving,
-    stacking order changes). The easiest fix for this kind of problem is to
-    simply create a new cairo context for each expose event.
+    go wrong is clip handling. You may not use cairo_reset_clip() on a
+    cairo_t on a cairo context created via gdk_cairo_create() or passed to
+    the GtkWidget::draw signal.
   </para>
 
   <para>

gdk/gdkcairo.c

@@ -78,34 +78,6 @@ gdk_cairo_create (GdkDrawable *drawable)
   return cr;
 }
 
-/**
- * gdk_cairo_reset_clip:
- * @cr: a #cairo_t
- * @drawable: a #GdkDrawable
- *
- * Resets the clip region for a Cairo context created by gdk_cairo_create().
- *
- * This resets the clip region to the "empty" state for the given drawable.
- * This is required for non-native windows since a direct call to
- * cairo_reset_clip() would unset the clip region inherited from the
- * drawable (i.e. the window clip region), and thus let you e.g.
- * draw outside your window.
- *
- * This is rarely needed though, since most code just create a new cairo_t
- * using gdk_cairo_create() each time they want to draw something.
- *
- * Since: 2.18
- **/
-void
-gdk_cairo_reset_clip (cairo_t            *cr,
-		      GdkDrawable        *drawable)
-{
-  cairo_reset_clip (cr);
-
-  if (GDK_DRAWABLE_GET_CLASS (drawable)->set_cairo_clip)
-    GDK_DRAWABLE_GET_CLASS (drawable)->set_cairo_clip (drawable, cr);
-}
-
 /**
  * gdk_cairo_get_clip_rectangle:
  * @cr: a cairo context

gdk/gdkcairo.h

@@ -32,8 +32,6 @@
 G_BEGIN_DECLS
 
 cairo_t *gdk_cairo_create            (GdkDrawable        *drawable);
-void     gdk_cairo_reset_clip        (cairo_t            *cr,
-				      GdkDrawable        *drawable);
 gboolean gdk_cairo_get_clip_rectangle(cairo_t            *cr,
                                       GdkRectangle       *rect);