[gtk/present-toplevel-2: 28/36] surface: document gdk_surface_translate_coordinates

[Matthias Clasen <matthiasc src gnome org>]

commit 25b90907ad5a663b06eb73b8dc5a338e714bc1c2
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Mar 9 13:46:42 2020 -0700

    surface: document gdk_surface_translate_coordinates

 gdk/gdksurface.c | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)
---
diff --git a/gdk/gdksurface.c b/gdk/gdksurface.c
index 63665e1877..a8621716f2 100644
--- a/gdk/gdksurface.c
+++ b/gdk/gdksurface.c
@@ -2962,6 +2962,24 @@ gdk_surface_handle_event (GdkEvent *event)
   return handled;
 }
 
+/**
+ * gdk_surface_translate_coordinates:
+ * @from: the origin surface
+ * @to: the target surface
+ * @x: coordinates to translate
+ * @y: coordinates to translate
+ *
+ * Translates the given coordinates from being
+ * relative to the @from surface to being relative
+ * to the @to surface.
+ *
+ * Note that this only works if @to and @from are
+ * popups or transient-for to the same toplevel
+ * (directly or indirectly).
+ *
+ * Returns: %TRUE if the coordinates were successfully
+ *     translated
+ */
 gboolean
 gdk_surface_translate_coordinates (GdkSurface *from,
                                    GdkSurface *to,